Please see the source of this guide in the template repository.
What is an API Quick Start
Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our templates GitLab repository.
API 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.
Contents of your Quick Start
Prerequisites
- 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
The main body
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.
What not to include
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.
Next steps
- What comes next?
Links to examples
- 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.
Explore other templates from The Good Docs Project. Use our feedback form to give feedback on this template.