Key points in this video

Two kinds of documentation materials: reference and conceptual.

Reference documentation is designed to be “reference material”. Contains all needed technical information, such as technologies, standards, endpoints, models, responses. Examples:

• endpoints list
• authentication information
• OpenAPI specification

Conceptual documentation is built around practical concepts. Examples:

• getting started guide
• guides for supporting tasks like setup, authentication, webhooks, handling rate limits, etc...
• guides for specific use cases
• tutorials
• FAQs

A good summary of the distinction: Conceptual docs guide consumers on curated paths; reference docs give them the tools to make their own.

Good manuals have both conceptual docs (how to turn on, how to clean, how to do X...) and reference docs (parts diagram, specification, safety information..)

Which should I have?

• For simple APIs, reference docs with a bit of commentary are often enough.
• For APIs that have multiple possible paths or are more complex, both are important. Ideally, you should have reference docs and guides for the most common use cases.

Optimize for your users’ common needs and use cases.

Exercise

Browse through the documentation sites listed below. Do they provide both reference and conceptual documentation? What kinds of use cases do their conceptual docs cover? How do they organise the reference and conceptual docs? You can share your findings in the course Discussion area.

• Mollie: https://www.mollie.com/en/developers
• Twitch: https://dev.twitch.tv/docs
• Basecamp 3: https://github.com/basecamp/bc3-api