Documentation guide¶
This guide gathers the collective wisdom of the Write the Docs community around best practices for creating software documentation.
This is a living, breathing guide. If you’d like to contribute, take a look at the guidelines for contributing to the guide. If you have any questions about contributing, you can send them along to guide@writethedocs.org.
Also feel free to send us any additions in any format to support@writethedocs.org.
New to caring about documentation?¶
Foundational resources¶
- Structuring your Documentation
Approaches to creating docs¶
- Documentation and product development
- Who writes the docs?
Markup languages¶
Tools of the trade¶
- Dictionaries
- Merriam-Webster
- https://www.dictionary.com | https://www.thesaurus.com | https://www.vocabulary.com
- Linguee (phrases/idioms)
- Lexique Pro (offline dictionary/term list builder…dated)
- Grammar and Complexity
- Translation Tools
- Keeping your documentation up to date
- Jekyll
Documentation guides¶
API documentation¶
Distribution¶
- Common Output formats
- Documentation Styles
- Slate
- Read the Docs Theme
- Alabaster
Writing environments¶
- Text Editors
- IDEs
- Live Previews
Talks & slide decks¶
Examples¶
Documentation comes in many variations. Here are some examples to inspire you:
- Stripe Great example of API docs
- Google Material Design Good examples of different layouts
- IBM Knowledge Center solid examples of code that isn’t necessarily API
Additional notes¶
Write the Docs resources¶
- Conference: https://www.writethedocs.org/
- Slack: Write the Docs
- Twitter: http://twitter.com/writethedocs
- Issues & feature requests: https://github.com/writethedocs/docs/issues
- Source repository: https://github.com/writethedocs/docs
