Documentation Guide

Welcome! We are excited that you are going down the path of creating more wonderful documentation in the world. This guide exists to provide both novice and expert writers a best practice handbook for building, structuring, and writing software documentation.

This is a living, breathing guide. If you’d like to contribute, fork us on GitHub! Also feel free to send us any additions in any format to guide@writethedocs.org.

Note

There are a number of topics that aren’t written yet. That means that you can write them! Please submit your thoughts and ideas, and you can contribute to making this guide better.

Now, let’s get started.

Writing Great Documentation

Documentation Culture at your Company

  • Integrating Tech Writers into the product process
  • Producing documentation inside a Support team

Inspiration

It’s always good to see the amazing things other folks have done. This gets us fired up. Check out these resources that we get inspired by:

Markup Languages

  • Markdown
    • Cheatsheet
    • Tutorial
  • Asciidoc
    • Cheatsheet
    • Tutorial
  • reStructuredText
    • Cheatsheet
    • Tutorial

Tools of the Trade

  • Keeping your documentation up to date

  • Automated testing
    • Link checking
    • Code Testing
  • Sphinx

  • Jekyll

Distribution

  • Common Output formats

  • Documentation Styles
    • Slate
    • Read the Docs Theme
    • Alabaster

Writing Environments

  • Text Editors
  • IDE’s
  • Live Previews

Write the Docs Resources