Skip to main content
ScaleMath

Place what does not fit

FAQs, glossaries, changelogs, examples and generated reference. Every real library has them and the four types do not describe them.

Real documentation libraries contain material the four types do not cleanly describe. A method with no position on it is not much use on a real library, so these are our rulings.

Orientation and overview pages

Legitimate and often necessary. Treat as explanation, but place it before the tutorial rather than after it.

Examples and snippets

Distinct from how-to guides. A how-to guide answers “how do I do this”. An example shows “here is this being done”, which a reader adapts to their own situation. Keep them as their own collection rather than forcing them into guides.

FAQ

Usually a symptom rather than a document type. Each entry is a how-to, a reference lookup or an explanation that somebody could not find. Prefer fixing findability. Keep an FAQ only where the questions are genuinely about the product's shape rather than its use.

Glossary

Reference.

Changelogs and release notes

Outside the four types. They are a product record, not documentation. Link from them to the affected pages, and never let them stand in for updating those pages.

Generated API reference

Reference, but produced by tooling. The editorial work is the surrounding descriptions, the examples, and the hand-written pages that link into it.

Need this applied to your documentation?

We audit, restructure and write product documentation for B2B software companies.

Product documentation servicesRun a free documentation audit
ScaleMath
  • Full stack, senior team: you get us, not just one person that's good at one thing.
  • Your strategic partner: we're here to serve you. Get our input on strategy, product, customer experience, UX, and more.
  • We've helped renowned companies like:
AtarimAAWPWP Fusion