Documentation as an Open-Source Practice

The provided text offers valuable insights on how to make open source repositories more welcoming and conducive to growth through documentation and contributions. Here's a summary of the key points:

1. Documentation Like Code: Make documentation an integral part of your open-source practice. Document features before coding and add comments as you go, making your codebase more understandable to future contributors.

1. Be Deliberate with Documentation: Avoid over-documentation within code files. Code should be readable and follow a style guide, with comments providing context where needed. Don't make your code harder to read with excessive comments.

2. Test and Maintain Docs: Just like code, documentation needs testing and regular maintenance. Update comments and related documentation when modifying code to avoid a last-minute documentation push.

3. Include Community-Focused Documentation: Share your project with the world through open source repositories. Essential files to include are:

   • README.md: Describe the project and its goals.
   • CONTRIBUTING.md: Provide instructions for potential contributors.
   • Optionally, a CODE_STYLE.md for code best practices.
   • CODE_OF_CONDUCT.md: Set community values and expectations.
   • CONTRIBUTORS.md or AUTHORS.md to recognize contributors.

4. Support End Users: Include tutorial-style documentation to guide users on how to use the software. Write documentation as if you are a beginner, and consider user testing to ensure it's meaningful and user-friendly.

5. Encourage Documentation Contributions: Consider documentation updates as valuable contributions. Encourage diverse voices to contribute to your documentation. Acknowledge and welcome code and documentation contributions equally to build a community around your project.

6. Make Documentation Inclusive: Foster inclusivity and accessibility in documentation:

   • Use welcoming and unbiased language.
   • Provide natural language translations.
   • Consider the reading level of your audience.
   • Explore alternative formats, like audio and visual components.
   • Optimize for screen readers.
   • Ensure A11Y compliance for web-based tutorials.

7. Connect with the Community: Seek resources and opportunities to connect with others working on open source and documentation. The Write the Docs community is recommended for comprehensive resources.

Incorporating these practices can help open source projects attract a wider audience, foster a sense of community, and provide valuable resources for both developers and end users.