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. (Or even worse yet... you finally get some help writing from other people) 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 your product could bring to them.
The secret is simple. Users come to your documentation for different reasons. And each reason requires a different approach to how you create and serve the purpose they came for.
Keep your documentation effective and working for you. Take an honest look at your documentation to see where these approaches can be applied.
When you're confused
Don't you hate it when a blog post goes on and on about xyz concept without getting around to how to actually implement it? If you're confused in your approach to writing your documentation, your customers will be too. 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 guides, technical reference, tutorials, and explanation. Each requiring a different writing approach and presentation.
Your documentation should be structured in a way that clearly indicates the specific section for each, separating them to avoid 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 the user 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 is 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 robot 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, functions, API reference, fields, attributes and methods. Describe how to work and operate the topic. Examples that demonstrate usage is recommended, but keep the explaining basic concepts, and achieving routine tasks for your How-to guides or 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 to 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 section separates them, giving them their own specific space. Again, this not only helps readers of your documentation, but makes writing and maintaining easier for yourself.
You can then ask yourself before writing a new feature or topic in; where should what I'm about to write live? What is it? A tutorial, how-to, etc.? As an added benefit, you can also use them to help direct you when you're not sure what to write. Just go down the list. Tutorial? Write it. How-to? Write it.
If you have existing documentations, scattered throughout are probably little chunks or subsections that could be categorized into one of these four types. Take them out, and put them where they belong.
Summarizing
- Decide which of the four categories makes sense for your product, and make individual sections for each.
- Migrate existing content that would be categorized as one of the four, into their corresponding new section.
- 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.
- When you're not sure what to write, Look to these categories as direction, going down the ones you chose for your documentation.