Reviewing docs: Best practices

We use a docs-as-code workflow to develop and publish product documentation using the same tools and processes as software code development.

All user-impacting updates on the codebase require corresponding updates to the relevant documentation in the docs repo.

Developers who know the feature best write the first draft of content for changes and new features (in PRs, in GitHub issues, in RFCs. Feature documentation is part of our development “definition of done.”

See the docs contributing guidelines.

Follow best practices for docs PR reviews, some of the best feedback comes line-by-line.

• Comment on PRs with actionable feedback (what the doc needs to be accurate)
• For in-line suggestions, use the GitHub suggesting feature

Consider using https://conventionalcomments.org/ to up-level the interactions.

We like GitHub emojis, too.