Merge pull request #18830 from newrelic/rhs-explain-automated-doc-edi…

…ting

Style guide: Add automated docs editing tips

src/content/docs/style-guide/writing-docs/writer-workflow/edit-automated-docs

@@ -0,0 +1,35 @@
+---
+title: How to edit automatically-generated docs
+---
+
+Some of the teams at New Relic automatically generate docs content from their GitHub repositories. When these automatically-generated docs appear in pull requests for the main docs repository (`https://github.com/newrelic/docs-website`), writers need to edit these somewhat differently than manually generated docs.
+
+<Callout variant="tip">
+  You can determine whether a doc is automatically generated by looking at the author in GitHub.
+</Callout>
+
+## Challenges with editing automatically-generated docs [#challenges]
+
+When we edit automated documentation, this doesn't address the underlying automation that will generate the same documentation for the next release.
+
+We need a routine for editing docs that solves two issues:
+
+* Ensures that the current, automatically-generated pull request is fixed for publication.
+* Ensures that the underlying source for these automatically-generated docs is changed. 
+
+## Best practices for editing automatically generated docs [#best-practices]
+
+When you're reviewing docs that were generated automatically from a repository, do the following:
+
+1. Make GitHub suggestions instead of pushing up changes directly. 
+2. Contact the docs hero for the team that pushed up the changes:
+    * This alerts developers to the suggestions you created. 
+    * They will accept or reject the suggestions.
+3. If the suggestions are accepted, merge those changes and publish the current release.
+4. If your suggestions also need to be made to the underlying source, create a Github issue in the corresponding team's repository. In that GitHub issue, link to the pull request in the public docs site. This will alert the development team to correct future automated releases. Here are some examples of repositories where you could create follow-up GitHub issues:
+    * Node.js (`https://github.com/newrelic/node-newrelic`)
+    * Ruby (`https://github.com/newrelic/newrelic-ruby-agent`)
+
+<Callout variant="tip">
+  For Node.js docs, you only need to create a corresponding GitHub issue if the suggestions you made were between the marker tags of an automatic doc (`{/* begin: compat-table */}` and `{/* end: compat-table */}`). Any changes outside those sections aren't affected by automation.
+</Callout>

src/nav/style-guide.yml

@@ -131,6 +131,8 @@ pages:
                 path: /docs/style-guide/writing-docs/writer-workflow/swiftype-search
               - title: Edit checklist
                 path: /docs/style-guide/writing-docs/processes-procedures/docs-site-edit-checklist
+              - title: Edit automated docs
+                path: /docs/style-guide/writing-docs/writer-workflow/editing-automated-docs
           - title: Doc types and templates
             pages:
               - title: Agent API guide template