The Quickstart

A quickstart helps new users get through their first experience using software.

There are at least two ways to write an API quickstart:

  • Bare-bones. An approach that takes the user as far as authenticating and making one successful connection with the API.

  • Grand tour. A longer tutorial that demonstrates the most important functionality of the API and ensures that your users know how to derive benefits from the API.

The bare bones approach

When the API is large and complex, you cannot include all the features in a single walk-through, either because there are a great many features, many kinds of users, or both. Rather than force-march a new user through every feature available, one way to go is a Quickstart that explains how to do most basic things:

  • Authenticate

  • Make a simple call that verifies connectivity and authorization (such as a system status check).

This approach is suitable when:

  • You have expert end-users who don't require a lot of hand holding.

  • You have many kinds of users, a great many featurs to document, or both -- in other words, the API is so feature-rich that you can't describe it all in one document and you can't try everything in one sitting.

  • You plan to quickly follow up with some additional procedures that explain how to use the main features of the API.

  • You're improving documentation, and you find that the API already has a great many How-to articles to explain the features, but happens to lack instructions for using it the first time.

If you use this method, stay tuned for an article about how to write the How-to articles that you might need to add next. Your users will definitely be looking for some guidance about how to use the features they need, as soon as they complete the quickstart.

The grand tour

This approach walks the user through every step of the first usage, from creating a token, to making a call, to interpreting the results.

The simpler the API, the easier it is to provide a detailed tutorial.

A really good grand-tour is a kind of tutorial that tries to do all the following:

  • Allow the user to experience the full power of what your API can do.

  • Make sure the user succeeds, and quickly. Make it seem easy even if that means demonstrating the easiest way to accomplish something, rather than the production method.

  • Demonstrate the key features that users will be leveraging 80-90 percent of the time.

A note about terminology

You might see other names for the Quickstart, like "Getting Started." I'll do my best to be consistent and clear about what I mean within this site, but keep in mind that it's not definitive.

The meaning of these terms isn't consistent from company to company -- or even from writer to writer -- so you have to be prepared to meet people who use different terms or think they mean something slightly different.

Further reading

For additional ideas about how to write the quickstart, see these resources: