Write the Docs: Documentation Guide

What it is

Write the Docs is a global community of people who care about software documentation: technical writers, developers, support staff and product people. Alongside its conferences, meetups, newsletter and Slack, it maintains a documentation guide written and reviewed by community members.

The guide is organised into six areas:

• Getting started: beginner guides, why documentation matters, best practices and how to build support for docs inside an organisation.
• Creating documentation: style guides, accessibility, reducing bias, and UX writing.
• Documentation approaches: docs as code and DocOps, where documentation lives in version control and goes through the same review and build process as software.
• Markup languages: introductions to Markdown, reStructuredText, AsciiDoc and XML.
• Documentation tools: choosing tools, writing platforms, testing docs and SEO.
• API documentation: tools and approaches for documenting APIs.

Is it worth it?

Yes, as a starting map. It does not teach writing from first principles the way Google's technical writing courses do, but it shows the whole landscape and links out to talks and articles from practitioners. The docs-as-code pages are especially useful for students, because that workflow (Markdown files in Git, pull request reviews, automated builds) is common in software teams and is easy to practise for free.

Prerequisites

None. Some pages assume basic comfort with Git; if you have not used it, a short Git tutorial first makes the docs-as-code material much easier.

How to use it

• Read the beginner pages and the docs-as-code page first.
• Use the style guide page to pick one guide to follow in your portfolio, such as the Google developer documentation style guide.
• Watch a few recorded conference talks on topics you are curious about. They are a good way to hear how working writers talk about the job.
• Join the Write the Docs Slack if you want to ask questions or see job posts.

Free vs paid

The guide is free. Conference tickets are paid, and Write the Docs publishes recorded talks for free after events.

License

The guide's content is published under a Creative Commons BY-NC-SA 4.0 licence.

Common questions

Is Write the Docs only for technical writers? No. The community explicitly welcomes developers and anyone who writes documentation.

Does it cover careers? Some pages and talks do, and the Slack has a career advice channel. For structured learning, pair it with a course.