What is a quickstart to you?

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. 😀

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 8 October 2018, in technical writing and tagged , , , , , . Bookmark the permalink. 12 Comments.

  1. Hi Sarah,

    I started out to comment here, but my though soon grew into a blog post in its own right: https://everypageispageone.com/2018/10/07/experts-read-more-than-novices/ #techcomm #eppo #contentstrategy The gist: the problem with givning long guides to novices and short guides to experts is that experts read more than novices.

    Mark

    • Thanks for your thoughtful reply, Mark. One thing to bear in mind: The purpose of the quickstart discussed in this post is to get the expert started quickly with the product. We’re perfectly free to give them longer, more in-depth guides as well.
      Cheers
      Sarah

      • Agreed, Sarah, that piece will often be useful to the expert user, and providing it is not at all to preclude the possibility of providing much more. The issue, to me, is far more about overwhelming the novice.

        But I would not call the document you provide for the expert “Getting Stated” or “Quick Start” or anything else with the word “Start” in it, for the simple reason that the expert, by definition, is not getting started. They are continuing. They are upgrading. They are installing or configuring and upgrade. But they are not starting. Because they are experts, they know exactly what they want to do at any given time. If you are providing information on installing, call that topic Installing. If you are providing information on configuration, call it Configuration.

        One of the biggest differences between novices and experts is that experts know what things are called and ask for them using their proper and usual names. Novices, on the other hand, have no idea what anything is called (though they may guess, by analogy with other similar tasks they have performed, though to the extent that they have relevant prior experience, they are not complete novices).

  2. What a thought-provoking start to he week. Thanks, Sarah, but cogitation and response will have to await me checking items off a long to-do list.

    • Hallo Nick
      Great to see you dropping by. Posting a conversation-starter like this post on a Monday morning is probably not the best start-of-week etiquette. Perhaps I should have waited until a lazy Friday afternoon. 😉 Good luck with that to-do list.
      Cheers
      Sarah

  3. Thanks Sarah for giving beefy real-world examples of what you are talking about. It gives me something to think with. I would be a novice with Google Compute Engine and I’d probably go with the more detailed guide because I’d figure I would need the extra information.

  4. Hi Sarah,

    I was looking for a thought-provoking article on Quick Start Guides, and thank you for providing one. To be frank, we have done exactly what you have discussed in this write-up about Quick Start Guides. Your article reconfirmed our thoughts on Quick Start Guides.

    Thanks much,
    Savitha

    • Hallo Savitha,
      Thanks for letting me know! It’s great to hear people’s thoughts about the ins and outs of these important guides. If we can help customers get started with a product, we help ensure they’ll keep using it and the docs. It’s really nice to hear that this post is provoking some thoughts and ideas.
      Cheers
      Sarah

  5. Hi again, Sarah. I love your definitions of “Quickstart” and “Getting Started” guides. I do usually try to define a document’s audience and/or purpose in its opening paragraph, and I’ll be sure to bear your definitions in mind when doing so.

    “Quickstart” for experts is fine, but I wonder if it’s the best name for a “reminder” guide. Some people are experienced users of a software package, but only use a particular module or feature very occasionally – perhaps annually. They need a summary of the salient points as a map reminding them how to reach their destination. The Quickstart should do it, but I wonder if they’d be put off by its name.

    I feel the need for some informal user research.

    • Hallo Nick
      That’s an interesting point. Instead of “quickstart”, perhaps we should have a name like “quick guide for experts”. If you do decide to undertake some user research, I’d be very interested in the results.
      Cheers
      Sarah

  1. Pingback: Experts read more than novices – Every Page is Page One

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: