Contributing to the Write the Docs guide¶
Welcome! The guides at Write the Docs are meant to address all aspects of software documentation. To contribute to a guide, read on to understand our guides and how you can help.
How to contribute¶
Anyone can contribute regardless of professional or tool experience. Contributions that respect our guide’s current effort and state are treated with respect.
To contribute, see the guide on contributing to the Write the Docs website
What to contribute¶
We especially need contributions in these areas:
Documentation best practices.
Developer tools or docs-as-code toolchains and workflows.
High-level discussions of common tools.
For help organizing a new topic within the current guide, ask in Slack, or file a GitHub issue.
Contribution guidelines¶
Use a friendly and encouraging tone. It’s a good way to write docs, so practice with docs about docs!
Attribute links and mention why linked resources are useful.
Use reStructuredText (.rst) (Markdown is also acceptable).
Focus content on general principles and best practices. Arguing over minor points impedes clarity.
Avoid enforcing personal preferences. For example, if you recommend a word choice, tell the audience why it matters.
Additionally, follow these guidelines when discussing tools:
Ensure your content is of interest to a general audience.
Avoid advocacy and plugs about your favorite toolchain, even if it’s open source.
Present specific use cases, how problems were solved, and what worked or didn’t work well.
Consider to first file a GitHub issue or contact a guide editor at guide@writethedocs.org.
Get help¶
If you have questions or need assistance in contributing, ask in the #wtd-website channel in Slack.
