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.

Getting Started with Documentation

• Starting off
  • Open Source Developers
  • Developers at a company
  • Enterprise Users
• A beginner’s guide to writing documentation
  • Why write docs
  • What to write
  • Next Steps
  • Template

Writing Great Documentation

• Documentation Principles
  • Overview, by component
  • In general, documentation should be...
  • Content should be...
  • Sources should be...
  • Each publication should be...
  • A documentation body should be...
• Docs as Code
  • Docs as Code at Write the Docs

• Structuring your Documentation
• Style Guides

Documentation Culture at your Company

• Engineering Organizations
  • State the problem
  • Start in engineering
  • Gather Input
  • Build a taxonomy
  • Make it easy
  • Have regular meetings throughout the process

• 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:

• https://github.com/PharkMillups/beautiful-docs
• https://github.com/showcases/projects-with-great-wikis
• Your link here

Markup Languages

• Markdown

  • Cheatsheet
  • Tutorial

• Asciidoc

  • Cheatsheet
  • Tutorial

• reStructuredText

  • Cheatsheet
  • Tutorial

Tools of the Trade

• Tools for documentation writing
  • Introduction to Sphinx
  • Sphinx Themes
  • Testing your Documentation

• Keeping your documentation up to date
• Jekyll

API Documentation

• Introduction
  • Automated Reference Docs
  • Test-Driven Documentation
  • Documentation Driven Design
• Languages
  • API Blueprint
• Generating Documents
  • Apiary
• Testing

Distribution

• Common Output formats

• Documentation Styles

  • Slate
  • Read the Docs Theme
  • Alabaster

Writing Environments

• Text Editors
• IDE’s
• Live Previews

Talks & slide decks

• Presentations
  • Theme
  • Beginner Presentations
  • Intermediate Presentations

Additional Notes

• About Write the Docs
  • Vision
  • Interesting approaches to documentation
  • Documentation Community
• Welcome to the Write the Docs documentation guide
  • Ways you can contribute
  • Where to start
  • What to leave out
  • What we expect from you, and what you can expect from us
  • For anyone new to GitHub and Git
• Community

Write the Docs Resources

• Online documentation: http://docs.writethedocs.org/
• Conference: http://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