Skip to main content

Guide to Writing Docs and Tutorials

The Basics​

"Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible." (Source)

Focus on answering a question or accomplishing a specific task. To ensure focused and actionable documentation, make sure you understand your learning objectives when creating new content. To do this, start by nailing down the Learning Objectives - which are the end goals. Working backwards in this way will cut out anything extraneous.

  • To create the Learning Objectives...
    • Focus on what will be built/implemented. By the end of every document, users should have built/implemented something or know how to use the newly obtained information. Set expectations by explicitly stating what the document will cover and what users will build/implement by the end
    • Use action verbs to ensure a user is building/implementing rather than passively reading code.

Voice​

Write with an instructive, guiding, and directive voice for a global audience. Use Active Voice!

Structure​

If the document is a tutorial, one suggestion outline is as follows to guide users through the learning experience and provides appropriate context:

  • Recipe Title
    • 1-2 sentences summary. Tell the reader what they will gain from reading this. Let them know if this is the document they are looking for before they read further.
  • Introduction
    • Answer for the reader - "Why is this topic important?"
  • Setup
    • Call out any required setup or data downloads
  • Steps
    • Use the steps you introduced in the Learning Objectives section
    • Break down the steps as well as add prose for context
    • If there is code, add comments in the code to help clarify for readers what each section is doing
    • Link back to relevant sourc code documentation
    • Think of it akin to creating a really practical blog post
  • Learn More
    • Link to any additional resources (e.g. related docs, API references, tutorials)

This is additional material.