The secret to good documentation

Four things you can do to help fix your new or existing documentations.

Is your documentation standing in the way of your customers learning your product? Imagine the scenario, you start to get into the weeds of writing your documentation. Days or months later you add some new content for that awesome new feature you just released. This happens a few more times. Eventually, somewhere along the way one of two things happen. Your docs start to suffer from TL;DR'onitis, or, it all begins to read so disjointed.

One of the most confusing things for people who are learning new things is the lack of continuity and tone. Not just voice, but in how you structure and format.

As I'm sure you'd agree, this is a big problem. A confused user is a potential happy customer never realizing the value of your product. 

The secret is simple. Users need your documentation for different reasons. And each reason requires a different approach to best serve the purpose they came for.

Besides the basics for SaaS product documentation, what else can be done to keep your documentation effective and working for you, and your customers? Let's dive in and take a look at some more detailed and fundamental strategies you can apply immediately.

When you're confused

If you're confused in your approach to writing your documentation, your customers will be confused when reading it. We will be going over four things you can do right after your done reading this to help fix your new or existing documentations. Your documentation will be easier to write, and easier to maintain.

Approach

As mentioned earlier, documentation needs to serve different purposes, depending on the needs of the user. There are four types, or categories you can use that aid users in accomplishing their goals. How-to guidestechnical referencetutorials, and explanation. Each requires a different writing approach and presentation.

Your documentation should be structured in a way that clearly indicates specific areas for each. Separating them prevents users from being unsure where they are, and where they can find the type of content they need.

Distinguishing these four styles in your documentation will tell you how to write, where to write it, and what to write. This foundation will save you tons of time, knowing exactly where everything goes, because each one has just one purpose.

How-to guides

How-to guides help a user to achieve a goal. They show a user how to solve specific or common problems they might face within your product. The best way to structure how-to guides are to take a user through the steps involved, with directions to solve an end goal. For example, how to import contacts.

When you are writing how-to guides, think of a user that already knows some of the basics of your app. This is a bit different than tutorials, so be mindful of the intended end user you are writing for.

Tutorials

Put yourself in the shoes of an absolute beginner to your app. This is where tutorials shine. They are learning oriented, with the specific mind set of instructing a newcomer exactly what to do next. You are teaching them how to complete a certain task through a series of steps.

What's crucial for your reader here, is that after completing the tutorial, they can make sense of the rest of your documentation, and as they finish more, your product itself.

Tutorials can be difficult to write. They need to be useful, accessible for a beginner, easy to follow, relevant and thorough.

Explanations

This category is a bit different than the rest. It's purpose is to provide understanding, give context or explain background/big picture topics. Explain why things are they way they are. (e.g. design decisions, technical constraints, etc.) For example, Markdown - how it's handled in snazzyDocs, and why it's different than the rest. 

This is where you can relax a little, and not be so specific (e.g. step 1, then step2, etc.). It's not the place for instruction or technical reference. You can turn off the teaching voice, share a little insider knowledge and personality. Imagine the reader trying to gain insight, rather than solve a problem.

Technical reference

As the name implies, reference sections are information based. These describe the inner-workings, as thoroughly and accurately as possible.

They typically include the code customers may interact with or use in your product. Such as, js snippets, API reference, fields, attributes and methods. Describe how to work and operate the topic. Examples that demonstrate usage is recommended, but save explaining basic concepts, or achieving routine tasks for your How-to guides and introductory tutorials.

Arrange these sections around the code. Remember, the main purpose of technical reference is to describe.

Structure

So how does all this come together then? How do you take the concepts discussed in this post and apply them to your own documentation? Structure. Taking these four categories and giving them their own specific space gives them the power. Power to not only help readers of your documentation, but make writing and maintaining it easier for yourself.

It allows you to ask yourself before writing a new feature or topic in; where should what I'm writing live? What is it? A tutorial, how-to, etc.? As an added benefit, you can also use this structure to help direct you when you're not sure what or how to write. Just go down the list. Tutorial? Write it like one. How-to? etc. 

If you have existing documentations, there is most likely little chunks of orphan content scattered throughout that could be categorized into one of these four types. Take it out, and put it where it belongs.

Summarizing

  1. Decide which of the four categories makes sense for your product, and make individual sections for each.
  2. Migrate existing orphan content that could be categorized into their corresponding new section.
  3. Before writing new content, ask yourself.. What am I writing? Does it belong to one of these four categories? Conform to your previously established typography, hierarchy, list types, colors, etc.
  4. When you're not sure what to write, Look to these categories as direction.