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, you can read our contributing documentation. Also feel free to send us any additions in any format to support@writethedocs.org.
Take a look also at the guidelines for contributing to the guide. If you have any questions about contributing, you can send them along to guide@writethedocs.org too.
New to Caring About Documentation?¶
Approaches to Creating Docs¶
- Documentation and product development
- Who writes the docs?
Markup Languages¶
- reStructuredText
- Cheatsheet
- Tutorial
Tools of the Trade¶
- Dictionaries
- Miriam-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
- SEO (Search Engine Optimization)
- 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
