Reference vs Explanation in the context of an HTTP API (SAAS) documentation

[jstasiak]

Hey all,

So I find myself struggling somewhat when it comes to separating explanation and reference in documentation of a SAAS API (so: a network service, not a library).

Here's broadly the "theoretical knowledge" content we'd like to document or have documented already:

1. The description of the individual HTTP API endpoints (request types, response types, error codes per endpoint, semantics etc.)
2. The way the API handles authentication (endpoint-independent)
3. The way the API handles pagination (endpoint-independent)
4. The way the API handles/returns errors (including connection to HTTP status codes; all endpoint-independent)
5. Backwards and forward compatibility guarantees (also endpoint-independent)
6. Rate limits and how to handle them (still endpoint-independent)
7. Order state transition diagram (the API has concept of orders and orders have a lifecycle, their status can change depending on various factors)
8. Interactions between payments and orders (orders made through the API have to be paid for and there are multiple ways this can occur)
9. Live mode vs test mode – mostly endpoint independent, a single API instance live API calls and test API calls for customer's convenience, this section describes the differences between them, some edge cases etc.

At first I took a very literal interpretation of

Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.

and

Explanation is a discusive treatment of a subject, that permits reflection. Explanation is understanding-oriented.

so I thought "clearly all of this information describes the machinery and at one point or another is needed in order to operate it; it contains information needed to get work done". But that would mean that all of the above would go into the "Reference" section and "Explanation" would be empty.

After having a look at Django documentation I'm now leaning towards something like:

• Put only the HTTP endpoint documentation in "Reference" (point 1 above)
• Put the rest in "Explanation" (points 2-9 above)

I'd appreciate any and all feedback, suggestions, corrections etc. Thank you in advance.

[honzajavorek]

My conclusion would be the same. I'd approach this with a rule of thumb "if it's endpoint-related, it's reference, if it's a concept across endpoints or independent on endpoints, it's an explanation". And I'd interlink heavily between those two where suitable.

[jstasiak]

Thank you @honzajavorek, I'm now convinced this is the way to go.