Quick Start Guides should be a clear, concise, ordered step-by-step procedure. They should describe the easiest way for readers to achieve a result that shows off the capabilities of your product. They should not delve into optimizations or advanced use cases.
- What knowledge do readers need before they begin
- What tasks do they need to complete (for example, software installation, environment configuration)
- Where to get tokens or API keys, if needed
Start by telling users what the Quick Start does. What task does this guide help the reader complete? Explain the basic operations that most users perform on the site, or the operations they can perform using the API.
Explain steps in the most logical order to complete a task. Each step should contain all the information necessary to complete it, and exclude any extraneous information. Include code samples in steps so that readers can copy and paste. Explain each code sample in comments directly before or after the example, so readers can understand how the API works.
Do not include setup information in your Quick Start, including anything that readers need to do to make their work environment compatible and ready for the API. Sometimes setup and Quick Start type information end up together in a single volume called a Getting Started Guide or similar. That's not necessarily wrong, but there are advantages to keeping the two types of information separate. Readers will often need the setup information, even when they no longer need the Quick Start lesson.
Do not include content that belongs in the reference section, including authentication, throttling, error codes, or a complete description of any feature.
Do not include content that belongs in the overview, including a general description of the product, or what the product can or can't do.
- What comes next?
- Jekyll. This SSG offers a good example of a Quick Start. Note that the setup info is in a separate document, and linked to in the first step.