Home » Learning Resources »

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
  • Docs as Code at other Conferences, Video Casts and Articles
• Style Guides
  • Technical Documentation
  • Why do I need a style guide?
  • Different styles for different folk
  • Writing Style
  • Other resources

• Structuring your Documentation

Documentation Culture at your Company

• Building documentation mindshare in a company
  • State the problem
  • Start in engineering
  • Gather Input
  • Build a taxonomy
  • Make it easy
  • Have regular meetings throughout the process
• Producing documentation inside a Support team
  • Advantages of working as a tech writer and support agent
  • Tips for support agents wanting to start in tech writing
  • Tips for tech writers wanting to start in support

• Integrating Tech Writers into the product process

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
• Your link here

Markup Languages

• Markdown basics
  • What is Markdown?
  • Why use Markdown?
  • How to use Markdown?
• This is a first-tier header
  • This is a second-tier header

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

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