Skip to content

Latest commit

 

History

History
34 lines (20 loc) · 2.19 KB

quickstart.md

File metadata and controls

34 lines (20 loc) · 2.19 KB
Raw

What is a quickstart

  • It should be a clear, concise, step-by-step procedure. (A set of numbered steps.)
  • It should describe the easiest way to get the intended results from the API, as opposed to the most optimized production modes or the most advanced uses of the API. Another way to describe a quickstart is that it shows potential users what your API can do, rather than tell them; if they follow the steps, any benefits (and the ease of obtaining them) ought to be apparent.

Contents of your quickstart

Prerequisites

Help users with any details that will prevent them from beginning.

  • Point to articles in the overview section that explain how the API works. (But don't incorporate any information that's belongs in the overview.)
  • Point the way to authentication, including how to get tokens or API keys, if needed.

The main body should follow these guidelines.

  • Start by telling users what the quickstart will do. What task does this guide help the reader to complete?
  • It should be explaining the basic operations that most users will want to perform on the site, or the operations they will perform when they use the API.
  • Steps should be explained in the most logical order to complete a task
  • Each step should contain all the information necessary to complete it and no more. Likewise, keep the entire quickstart as brief as possible.
  • A step should include code samples (examples) that users can copy and paste, if executing code is necessary. Each code sample should be explained in comments that follow directly after the example, so newcomers can quickly understand how the API works.

The quickstart should not include:

  • Things that belong in the reference section, like a complete description of any endpoint. If users need information that is located in another doc, use the quickstart to show them where it can be found.
  • Things that belong in the overview.

Some examples