Knowing how to document your app can be challenging. If you’re new to crafting documentation, you may be asking questions like:
- Should I write a user guide?
- How many tutorials do I need?
- How can I make what I just wrote better?
A large part of my job is helping people answer these questions, and in this blog I’d like to focus on one thing that you can do to help create useful and consistent content.
Guide your writing by using templates
I’d be a very slow writer if I had to create all new documents from scratch (if you want proof, just ask my colleagues how long it took me to write this blog post).
The truth is that writing documentation is hard and being confronted with a blank page is one of the hardest parts. It can be a monumental task to figure out what to say, even when you know what you want to write about. Fortunately, using templates is a shortcut that can take some of the pressure off of writing.
There are many reasons why it is a good idea to use templates, but I’d like to call attention to two especially important benefits:
- Reduces the effort necessary to plan and write new documentation
- Creates a predictable structure for each type of document, making it easier for readers to use
Below are three templates from our Writing toolkit for developer documentation, which you could adapt to meet your needs.
Concept page
A concept page explains complicated concepts simply by providing an overview of a particular topic, including relevant contextual information. These pages focus on the why not the how, and answer questions like these:
- Why would I want to use this?
- What happens if I don’t use this properly?
- What best practices apply to this topic?
Concept pages are a great place to include broader-level screen captures, images, and diagrams, especially for complex topics. You may also include other media, such as videos or short animations.
Task page
A task page provides instructions for completing a piece of work by providing a simple, straightforward description of how to do a particular task. These pages focus on the how not the why, and answer questions like these:
- How can I create a Marketplace vendor account?
- How do I view sales reports?
- How do I update the Atlassian SDK on Windows?
Task pages should not repeat content from concept pages or resemble guided walkthroughs in tutorials. Instead, the main purpose of a task page is to help the reader get something done.
Create a task page when you need to document:
- a procedure that many users will complete.
- a multi-part effort (such as packaging and submitting a server app to the Marketplace).
- tasks that are unclear or have created a lot of support issues.
Tutorial page
A tutorial helps the reader learn a new skill or technique by walking them through an example, step-by-step. Tutorials briefly explain how concepts work together without being a repeat of a conceptual page or as straightforward as a task page. Below are a couple examples of use cases that a tutorial could address:
- Learning a new programming language: What do I need to know in order create a program that prints “Hello, world!”?
- Learning graphics editor software: I’d like to learn how to manage layers so I can export specific objects. Is there a guide that explains this in detail?
Often, tutorials are written to help newer users complete first tasks or learn new concepts, but tutorials are also appropriate for all skill levels. It is helpful to state the intended skill level in the introduction so that readers can identify if the tutorial is right for their needs.
Below are some tips for creating a great tutorial:
- Clearly describe the outcome at the beginning, using visuals if possible.
- Stay focused on the task at hand, and don’t add side projects.
- Provide a way to verify progress after each major step.
- End with a logical next step.
It is okay to deviate
We’ve spent a lot of time designing the templates above, and I’ll let you in on a little secret: Sometimes it is okay to deviate from a template. But you should do so with care, especially if you’ve never written a particular type of document before.
Here are a couple of scenarios that may happen when you’re new to writing with templates:
- As you’re writing, you find that your page is getting long, really long.
- The content just doesn’t fit into the template, and you find that you’re making up content just to satisfy the template’s design.
For the first scenario, it may be as simple as breaking the page up into parts, but you may also find that the documentation process has revealed some useful product feedback. I’ve experienced this a number of times over the years, and while it isn’t easy or fun to do, it has helped lead to better product outcomes.
The second scenario is easier. Maybe you need to use a new template, or maybe you can trim a few sections from the template to support the content. Just be sure that you’ve covered the necessary information adequately. For example, it is okay to have a task page with a single set of instructions if that’s all there is to say.
More tips coming soon
Stay tuned for other posts in this series with more helpful tips on writing documentation for your users.