Minimal viable documentation#
Documentation must exist here for a feature to be considered complete. Features aren’t finished until they’re documented in a way that users can discover and understand them.
We use a simple structure that prioritizes actionable information first, followed by technical details for those who need them.
Documentation template#
(a-myst-label)=
# A short, discoverable page title
A few sentences answering: What does this allow you to do? Why is it useful? When should you use it? Who is it for?
## How it works
A few sentences describing how to use it, and what it looks like when it works. What should you expect to happen as a user?
## Where to learn more
(optional) Links to upstream documentation or product-specific documentation where users can go into more detail.
## Who can access it?
(optional) If this is only available to subsets of communities or users, state which users, roles, or membership/service configurations can use it.
Key principles#
Answer value questions first: What, why, when, who - help readers decide if this applies to them
Show how to use it: Actionable steps and what to expect
Technical details are optional: Add deeper resources only if needed
Keep it brief: A few sentences per section is often enough