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.

Challenges with editing automatically-generated docs

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

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)