Documenting getting started section
Following the Overview section, you usually have a “Getting started” section that details the first steps users need to start using the API.
- Common topics in getting started
- Show the general pattern for requests
- Sample Getting Started sections
- Hello World tutorials
Common topics in getting started
The “Getting started” section should explain the first steps users must take to start using the API. Some of these steps might involve the following:
- Signing up for an account
- Getting API keys
- Making a request
- Reviewing the endpoints available
- Calling a specific endpoint
Show the general pattern for requests
When you start listing out the endpoints for your resources, you just list the “end point” part of the URL. You don’t list the full resource URL that users will need to make the request. Listing out the full resource URL with each endpoint would be tedious and take up a lot of space.
You generally list the full resource URL in a Getting Started section that shows how to make a call to the API.
For example, you might explain that the domain root for making a request is this:
And when you combine the domain root with a sample endpoint, it looks like this:
Once users know the domain root, they can easily add any endpoint to that domain root to construct a request.
Sample Getting Started sections
Here’s the Getting Started section from the Alchemy API:
Here’s a Getting Started tutorial from the HipChat API:
Here’s a Getting Started section from the Aeris Weather API:
Here’s another example of a Getting Started tutorial from Smugmug’s API:
I like how, right from the start, Smugmug tries to hold your hand to get you started. In this case, the tutorial for getting started is integrated directly in with the main documentation.
If you compare the various Getting Started sections, you’ll see that some are detailed and some are high-level and brief. In general, the more you can hold the developer’s hand, the better.
Hello World tutorials
In developer documentation, one common topic type is a Hello World tutorial. The Hello World tutorial holds a user’s hand from start to finish in producing the simplest possible output with the system. The simplest output might just be a message that says “Hello World.”
Although you don’t usually write Hello World messages with the API, the concept is the same. You want to show a user how to use your API to get the simplest and easiest result, so they get a sense of how it works and feel productive. That’s what the Getting Started section is all about.
You could take a common, basic use case for your API and show how to construct a request, as well as what response returns. If a developer can make that call successfully, he or she can probably be successful with the other calls too.
37/96 pages complete. Only 59 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.