From 3c73fb20072d3b7393f73b5e0589606b4eec84e2 Mon Sep 17 00:00:00 2001 From: Rob Siebens Date: Wed, 2 Oct 2024 12:08:45 -0700 Subject: [PATCH] fix(styleguide): Add automated docs editing tips --- .../writer-workflow/edit-automated-docs | 35 +++++++++++++++++++ src/nav/style-guide.yml | 2 ++ 2 files changed, 37 insertions(+) create mode 100644 src/content/docs/style-guide/writing-docs/writer-workflow/edit-automated-docs diff --git a/src/content/docs/style-guide/writing-docs/writer-workflow/edit-automated-docs b/src/content/docs/style-guide/writing-docs/writer-workflow/edit-automated-docs new file mode 100644 index 00000000000..74cec0a4d17 --- /dev/null +++ b/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. + + + You can determine whether a doc is automatically generated by looking at the author in GitHub. + + +## 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`) + + + 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. + \ No newline at end of file diff --git a/src/nav/style-guide.yml b/src/nav/style-guide.yml index addac1a660b..9ca14ac8bca 100644 --- a/src/nav/style-guide.yml +++ b/src/nav/style-guide.yml @@ -129,6 +129,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