Sharing Knowledge: Writing Good Docs for Quick Approval

The importance of writing good documentation for open source projects and best practices for quick approval

• Good documentation has a profound impact on the visibility, quality, and inclusivity of open source projects
• Developers prefer documentation to contacting support or talking to an actual person
• Most developers see documentation and its incompleteness or its lack of existence to be a huge problem in the community
• The goal is to write inclusive, accessible, high-quality documentation in pull requests designed for quick approval
• Best practices include structuring documentation using content templates, writing with clarity and technical accuracy, and avoiding common pitfalls that trap PRs in prolonged reviews
• Writing in second person and focusing on the user's perspective is the most useful thing you can do
• Specify what kind of review you want and set context for your reviewer

The story of Tony and Maria illustrates the importance of considering the audience when writing documentation. Tony's focus on speed led him to copy and paste existing content without considering the needs of his audience. Maria, as a senior developer and doc reviewer, had to spend more time reviewing and editing Tony's PR to make it more user-friendly and accurate.

The goal of this talk is to increase your ability to write good documentation that gets approved quickly. Good documentation has a profound impact on the visibility, quality, and inclusivity of open source projects. Documentation creates a shared understanding of work, helps onboard new developers, and improves the overall quality and reliability of the project.Based on Jared's experience leading Kubernetes SIG Docs from 2016 to 2020, this presentation walks developers through best practices for creating inclusive, accessible, high quality documentation in pull requests designed for quick approval. This demonstration includes how to structure documentation using content templates, write with clarity and technical accuracy, and avoid common pitfalls that trap PRs in prolonged reviews.Click here to view captioning/translation in the MeetingPlay platform!