When someone asks you to create a quickstart guide, what do you envisage? More importantly, what does the requester envisage, and what do your readers expect from such a doc? Is a quickstart the same thing as a getting-started guide? Are you all starting on the same page? 😉
I’ve found that people mean different things when they talk about quickstart guides. Confusingly, people mean different things when they talk about getting-started guides too. For some people, quickstarts and getting-started guides are the same thing, but people differ about what that thing actually is. For other people, quickstarts and getting-started guides are separate docs with disparate goals.
As a result, when people get together to discuss the requirements for such a doc, the discussion can be long and complex. Debate may become quite heated. At that point, it’s a good idea to take a step back and check everyone’s initial assumptions.
I started this post with a number of questions. It may have felt like a barrage of questions! Actually, the crucial question is this:
“Who is the intended audience for the guide?”
Here’s an approach that appeals to me:
- A quickstart guide is for domain experts.
- A getting-started guide is for domain newbies.
Let’s take a look at how the approach pans out.
Quickstart is for experts
The quickstart is for readers who know the problem space and know exactly what they need to do.
As a user, I know what I need to do. Just show me how do it with your particular product.
These are domain experts. They know their field. Your product targets one or more tasks in that field. The experts have performed the tasks untold number of times, using various tools and processes. Now they just need to know how to drive your specific product to complete the task.
In the quickstart, they need to see:
- Where to find the product. This may be a web address, or a download link, or an address to a brick-and-mortar store.
- How to get any required access keys or authentication credentials.
- How to configure the product. For a developer-focused product, this usually involves creating a hello world application. For an end-user product, this may mean setting up a corporate or user profile and choosing other preferences.
- How to get started. This is often a walkthrough of a simple but common use case, which helps the reader learn the patterns of your product and map your terminology to theirs.
The domain experts don’t need the following information in a quick start guide (though they should have easy access to these items if they do need them):
- Detailed descriptions of the concepts relevant to the domain and the product.
- A detailed walkthrough of a complex use case.
- Explanations of why they’re performing each step.
Here’s an example of a quickstart guide for Google Compute Engine.
Getting-started guide is for newbies
The getting-started guide is for people new to both the problem space and the product.
As a user, I’m not sure exactly what I’m doing here. Help!
They need an introduction to the most important concepts, full context about each step they’re performing, and detailed setup instructions.
Typically the guide needs to assume some existing knowledge of the problem space. The writer needs to decide just how much prior knowledge to assume.
The guide to creating and starting a virtual machine on Compute Engine is a good example. It’s not titled as a getting-started guide, but I think it has the characteristics of one. It assumes the reader knows what a virtual machine is, but gives them plenty of context from that point onwards.
The marketing approach
I’ve had a number of interesting discussions with marketing teams about what should be in a quickstart or a getting-started guide. These discussions don’t generally distinguish between the two types of guide. The marketing approach views the document as an introduction to the values your product offers, why people should use it, and who else is using it.
The target audience is usually the business decision maker – the person who’ll decide whether to buy the product.
The product overview for Compute Engine is an example of such a doc.
What to do about these varying interpretations?
If people are coming to our docs with different expectations of what they’ll find in a quickstart or a getting-started guide, how can we ever hope to satisfy them all?
An ideal solution is to describe the purpose and intended audience at the top of the doc. Make it clear what people can expect before they commit to reading the doc.
That simple step may help prevent numerous complaints and negative ratings on our docs. Even better, it’ll help numerous readers know what to expect or at least send them away with a smile rather than a frown.
If people are coming to meetings with different expectations of the doc we’re building, how can we ever hope to get agreement?
A good solution is to make sure we’re all using the same terms and definitions at the start of the meeting. For example, the Compute Engine docs have clearly defined “product overview” and “quickstart” guides, and a getting-started guide in the “how-to guides” section. If people can agree on a breakdown of document types that suits the organisation, then everyone knows where to channel their energies. We’re all on the same page!
Best explanation ever
Here’s the best explanation I’ve seen of the purpose of a guide, from the Jupyter/IPython Notebook Quick Start Guide:
“Briefly, if someone gave you a notebook to run and you don’t know what a notebook is, this document is for you.”
And yes, Jupyter’s definition of a quick start guide differs from mine. Plus, they use two words for “quick start” instead of one. 😀