Part 2 of 7 · 2 min read
The problem and the kinds of documentation
Why a copied example fails, and the six kinds of page you will meet.
You find an example in a tutorial. You copy it, run it, and get an error, or worse, it runs and returns something strange: an answer cut off in the middle of a sentence, or a different result every time. Nothing in your code looks wrong.
The cause is almost always something the documentation tells you and the example did not: a parameter was renamed, a default is not what you assumed, a limit is lower than you expected. Documentation is where those facts live. An API (application programming interface, module 3) is a set of rules for talking to a program, and its documentation is the rulebook.
Not every page of a documentation site is the same kind of page:
| Kind | What it is for | How far to trust it |
|---|---|---|
| Quickstart | Gets one call working | Good for the first request only |
| Guides and concepts | Explain how to think about the product | Good for design decisions |
| API reference | The exact list of endpoints, parameters and responses | The authority on what is accepted |
| OpenAPI or SDK reference | The same facts in machine-readable or code form | Precise, and can drift from the prose pages |
| Changelog and migration notes | What changed and what is deprecated | Read before upgrading and when something breaks |
| Status page | Whether the service is up right now | Check first when "nothing works" |
OpenAPI specification
A JSON or YAML file that describes an HTTP API: its base URL, how to authenticate, every endpoint, each parameter with its type and whether it is required, and the possible replies. Many documentation sites are generated from one, and tools can generate client code, test servers and tests from it.
Deprecated
Still working, but marked as going away. Do not build new code on it.
Check yourself
- Which kind of page is the authority on what a parameter accepts?
- Where do you look first when an example that worked last month now fails?