Documenting at the API Level
👉 Writing Tip #6: Make things real by adding examples
Key points in this video
You don't have to have a "general" section, but it helps to give your users an overview of what to expect.
Some considerations for what to put in your "general" section.
- Information about the documentation
- description (capabilities, technical information)
- pre-usage info (signing up, creating an app)
- base URL, versioning
- rate limiting
- contact information
- error handling
- common parameters
- request/response formats, headers, structure
If you have a lot of content in some of these sections, you should consider creating separate guides.
Some tips when writing general documentation:
- Avoid information overload. Not all information is helpful, or needs to be presented NOW.
- Write for your audience. Use terms they'll know, provide links to additional documentation.
- Don’t be afraid to repeat yourself. For example, you might need to describe the common parameters in the general section and again for each endpoint. A good dose of repetition can aid clarity.
- Don’t over-generalize. If the information doesn't apply to all or most endpoints, don't put it in the general section.
Some examples we looked at:
Hopefully you’ve set up the API infrastructure for Hazam. Next up: documenting at the API level.
What pieces of general information do you think will be important for Hazam users? Come up with a sample introductory section containing these. You can share your results in the Discussion area.