If asked, probably any person would answer you what a quickstart guide (or a QSG for short) is, even not being a technical writer themselves. But most of them would probably confuse terms quickstart guide and getting-started guide. If you’re a technical writer or work in a similar position, you, most likely, know the difference.
If not or you’re not sure — don’t despair. Better let’s take a quick look at what a quickstart guide is and how it’s different from getting-started guide and then dive into details about the former.
Quickstart Guide is, basically, a compressed version of user manual. But so is a getting-started guide! Yes, they are somewhat similar — their goal is to provide as much info in as little volume of information as possible, quickly getting the user acquainted with your product. And yet they are completely disparate, because they differ heavily in their target audience.
A getting started guide is intended for people who are not familiar not only with your product, but with other similar products — basically, for ‘newbies’ in that field or area. In this guide users wanna see some basic concepts of your product, ideally — detailed setup guidelines and explanations about each step they are making and why they are doing what you’re telling them to do.
QSG, on the contrary, is for professionals in that particular area. They are familiar with your product, or used something similar and they don’t want to know what to do — they wanna know how they do it with your particular product.
Now that we’ve got that out of our way, let’s move on and talk about quickstart guides.
A very important thing is to base QSG on your user manual. After all, it’s what it is — a short version of the latter. If you start writing one thing in your qsg and manual has completely different structure and topics, it will be highly confusing. The best practice here (at least in my experience) is to take table of contents from user manual and work your way down. This way your qsg will have the same structure and you will be sure to touch on every subject you have to. Of course, you can skip some parts, if you think they won’t fit in the quickstart guide.
Structurally, quickstart guides can be written either in sequential order, where your users have to complete steps in a specific order, or just as a series of tasks, which can be done in any order, but all of them are required to be completed. It’s totally up to you and depends on your product. Also don’t be afraid to incorporate visuals — insert screenshots or photos with instructions or guides on them. Emphasize the button user needs to click, point at it with an arrow — do everything to make sure it’s perfectly clear what has to be done. But don’t treat your audience as newbies — if, say, your tool has only one ‘NEXT STEP’ button on the page, just say “continue to next step” instead of “find a little blue button in the left-hand bottom corner of the page with ‘next step’ text on it”.
Also take note of the user feedback. Check the most viewed sections of your knowledge base or your FAQ section and correct your qsg accordingly. After all — you’re writing this for users, so you have to provide them with info that is relevant and will help the most.
Quite briefly, but we’ve covered the basics here. The article could’ve ended here, but I feel like I have something else to offer, so I’m going to share some good practices you can use while writing a quickstart guide.
- Try addressing your users directly. Don’t distance yourself from them. Avoid using phrases like “User should this… User have to that…”. Speak directly to them — “You need to… You have to…”. They will feel that you’re talking to them, instead of referring to some abstract ‘customer’ or ‘user’.
- Explain the outcome and state the overall purpose of the guide. Users need to see what they will get at the end of QSG without reading it first. At the very beginning they should already know if this guide is right for them or they should continue searching.
- Clear headings are your friends. Don’t overload them with complex sentences, and don’t make them too vague as well. Users need to know what each section is about without reading it.
- Along with headings, you should not overcomplicate the text itself. Use plain, simple sentences so users can run through your manual quicker.
- Use consistent formatting throughout the document. When you use the same formatting in each section, users will quickly grasp it and finding info will be easy-peasy, ’cause, for example, they will know that they find code snippets at the end of each section, and some tips are provided in italic.
Have a nice day!
Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors