Real-world Patterns 2: Reference Docs
Key points in this video
Reference docs usually follow a certain structure
- An Overview section that lays out basic info about the API
- Sections about authentication, rate limiting, errors and any other info specific to the API
- List of endpoints, with some logical grouping
- Each endpoint should have basic technical info (URL, parameters, response structure), but can also include helpful commentary or contextual info.
- Tip: Make sure to include a description of what the endpoint does. The endpoint’s URL might make that obvious to you, but your users might not get it as easily.
Reference docs can be single-page or multi-page
- Single-page sites means less waiting for pages to load. The maintainer can also avoid implementing a custom search functionality if they don't have th resources, since browser find (Ctrl-F/Cmd-F) is available.
- Multi-page references are useful if you have a lot of endpoints and you go into detail on them.
- Large APIs can be single-page at group level
- Tip: On a single-page site, make sure to use anchors and a persistent sidebar so users can get around easier.
- Tip: On a multi-page site, avoid splitting items too much to avoid fragmentation
- Tip: A good sidebar or table of contents provides users with the “big picture”, single or multi-page.