We’ve been exploring a lot of Open Source software recently, and as you might expect, their documentation varies a lot.
Most companies are really interested in anything that can reduce their support load, but they don’t have 30 years of experience like we do… however we can’t write software so it seems fair that we give back some expertise!
You won’t put all of these items into a helpdesk article, but you should consider if your article needs each one. Want to see this in action? click here for an example article.
Remember- 1 hour spent writing documentation equals 10 hours doing support, according to a study I just made up.
State the Goal
This is a clear outline of what the reader can achieve if they follow the guide. It’s at the top so someone looking for a guide with a particular purpose can quickly skim this short summary.
Background (Optional)
You won’t always need a background, but for more complex projects you might want to include some extra info so that a user who isn’t an expert can grok what’s happening.
Requirements
This one is pretty self evident- you need to state the requirements of your procedure so users don’t get halfway through and find they are missing something important.
Summary of Steps (Optional)
If it’s a long article, you might want to include a list of the steps, for extra points make these links to skip directly to the bit a user needs
Instructions
This is where your actual article starts- it’s a long way down, isn’t it!
Each section has a numbered step and a sub heading describing what happens during this stage. You will include Text, Links, Pictures, Video as appropriate. If the step has commands that might be variable give 2 examples– one basic and one more complex.
- Language must be friendly and accessible
- Words must be used consistently- don’t use 2 words for the same thing unless you also add an explanation of why
- A picture really is worth a thousand words
- Big red arrows help too!
- Add captions to pics if the article is web accessible
- Have a template and use it
- Know your audience and pitch to their skill level or a bit below
- If your product is super complex, that’s an engineering problem. Make videos, and make your product easier to use!
- Copy the people who are best in class- Apple are particularly good with language
- Make a bold / coloured box / callout if there’s something important in a step- eg. in a recipe including cream, a warning to not boil the liquid
- Use empty space around an important concept to emphasise it- sometimes nothing means something
- Is there code, variables, etc. in a step? Did you explain where they come from? Where they go? How they work?
- Don’t use outbound links if getting to the next step requires info from those links! Make the info explicit in your article
- Some assumed knowledge is ok! If your product has a Docker deployment method, you can assume the reader knows something about Docker- but make sure YOUR instructions make sense
- Don’t try to squash too many concepts, methods, etc. into a single article. Er, maybe this article should have been a book…
Other Methods (Optional)
There is often more than one way to achieve a particular task, example many Open Source projects are available as –
• Linux binaries
• macOS
• Windows apps
• SAAS or Cloud
• Docker / Kubernetes
A guide for installing each of these may have many of the same instructions- BUT your key goal is to help users, not making help docs impossible to follow. Forcing users to skip backwards and forwards is a recipe for disaster!
You can accept that each install method needs it’s own article, or you can combine them and hope- but you MUST check the article for each method to ensure that it can be easily followed, and if there are subsequent articles, that there isn’t any missing information between the end of one and the start of another.
Your instructions aren’t finished unless the product is working!
If you got an engineer to write the instructions, they are famous for not quite finishing the docs because they never wanted to write them in the first place- check they are complete.
Is it hard to follow the exact method for a particular install type? Make it a separate article- if you suddenly have hundreds or thousands of users, it’s much easier to fix an article than to deal with the support load of hundreds of people who can’t follow the article.
Remember- constantly going back to your ‘single source of truth’ to add addenda or warnings to suit a specific group of people will mess up your templates and eventually become unreadable!
Testing & Troubleshooting
You should provide a test for each step, but if that’s not possible add a testing and troubleshooting section at the bottom.
Add in a list of common problems and their respective solutions, and for tests include the failure codes as well as the success codes.
Does your test require extra skills or tools? Then it’s a bad test, and you should be allocating resources to fixing that.
Is there an external method for checking readiness? That should be inside your product!
How to Get Support
The goal of every tech support article is to allow users to get back to work ASAP if they have an issue, or to make it easy to do something new.
You are empowering them by passing on your skills in the hope that they don’t need direct attention- because that’s going to cost someone money or sanity.
If you want to maximise both of these things, your documentation needs to be clear, succinct, easy to read and follow.
But you also need to respect the fact that some people won’t read it, no matter how good it is. For those people, you need to cover the whole thing with a Policy. But that’s out of scope for this article- don’t take too much space telling your life story!
Clearly state what the next steps are if there are issues- Slack, Discord, Github, Helpdesk, and er, smoke signals.
Legal (Optional)
Bah, I only fix computer problems- give the human problems to legal. You’ll probably be required to have some disclaimers at the bottom, but these are baked into your platform, right?
Want to see this in action? click here for an example article