Patterns and structure for writing functional documentation including guides, conceptual explanations, tutorials, and best practices documentation.
Functional documentation explains concepts, guides users through workflows, and helps them understand "why" and "how" things work. This differs from API reference, which documents "what" each endpoint does.
| Type | Purpose | Key Sections |
|---|---|---|
| Conceptual | Explains core concepts and how things work | Definition → Key characteristics → How it works → Related concepts |
| Getting Started | First task with the product | Intro → Prerequisites → Numbered steps → Next steps |
| How-To | Task-focused for specific goals | Context → Before you begin → Steps → Verification → Troubleshooting |
| Best Practices | Optimal usage patterns | Intro → Practice sections (Mistake/Best practice) → Summary |
Start every document with what the reader will learn or accomplish.
✅ This guide shows you how to create your first transaction in under 5 minutes.
❌ In this document, we will discuss the various aspects of transaction creation.
Address the reader directly.
✅ You can create as many accounts as your structure demands.
❌ Users can create as many accounts as their structure demands.
Use for current behavior.
✅ Midaz uses a microservices architecture.
❌ Midaz will use a microservices architecture.
Indicate what the section covers or what users will do.
✅ Creating your first account
❌ Account creation process overview
2-3 sentences maximum. Use bullets for lists.
| Element | Usage |
|---|---|
| Info box | > **Tip:** Helpful additional context |
| Warning box | > **Warning:** Important caution |
| Code examples | Always include working examples for technical concepts |
| Tables | For comparing options or structured data |
Use --- to separate major sections. Improves scannability.
Before writing any functional documentation, MUST load relevant standards:
ring:voice-and-tone skillring:documentation-structure skillHARD GATE: CANNOT proceed with functional documentation without loading these standards.
| Condition | Decision | Action |
|---|---|---|
| Feature not implemented | STOP | Report: "Cannot document non-existent feature" |
| Feature behavior unclear | STOP | Report: "Need confirmed feature behavior" |
| Target audience undefined | STOP | Report: "Need audience definition for appropriate depth" |
| Prerequisite knowledge undefined | STOP | Report: "Need to know what readers should know first" |
| No working examples available | STOP | Report: "Need working examples to include" |
These requirements are NON-NEGOTIABLE:
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Missing core sections, incorrect information | No examples, wrong feature behavior described |
| HIGH | Missing value statement, no next steps | Reader doesn't know why they're reading or what to do next |
| MEDIUM | Voice/tone violations, structure issues | Third person, long paragraphs, title case |
| LOW | Minor clarity improvements | Could flow better, additional context helpful |
| User Says | Your Response |
|---|---|
| "Skip examples, explain the concept" | "CANNOT skip examples. Examples make concepts concrete. I'll include working examples." |
| "We'll document later, feature is done" | "Documentation is part of the feature. CANNOT ship undocumented features. I'll write the docs now." |
| "Just a quick README overview" | "README is not functional documentation. MUST create proper guide with examples and next steps." |
| "Developers don't need handholding" | "Good documentation helps ALL developers. I'll write clear, complete guides." |
| "Copy from the design doc" | "Design docs are not user docs. MUST rewrite for user audience with examples." |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Feature is intuitive, minimal docs needed" | Intuitive to you ≠ intuitive to users | MUST write complete documentation |
| "Design doc already explains this" | Design docs serve different audience | Rewrite for user audience |
| "Examples are extra work" | Examples are the most valuable part | MUST include working examples |
| "Users can figure out next steps" | Users shouldn't have to guess | MUST include clear next steps |
| "Quick overview is enough" | Overviews don't enable task completion | Write task-oriented guides |
| "Code comments are documentation" | Comments serve developers, not users | Write separate user documentation |
Signs that functional documentation already meets standards:
If all above are true: Documentation is complete, no changes needed.