6.2 KiB
name, description, trigger, skip_when, sequence, related
| name | description | trigger | skip_when | sequence | related | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| writing-functional-docs | Patterns and structure for writing functional documentation including guides, conceptual explanations, tutorials, and best practices documentation. | - Writing a new guide or tutorial - Creating conceptual documentation - Documenting best practices - Writing "how to" content | - Writing API reference → use writing-api-docs - Reviewing documentation → use documentation-review - Writing code → use dev-team agents |
|
|
Writing Functional 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.
Document Types
1. Conceptual Documentation
Explains core concepts, architecture, and how things work together.
Structure:
# Concept Name
Brief definition paragraph explaining what this concept is and why it matters.
## Key characteristics
- Characteristic 1: Brief explanation
- Characteristic 2: Brief explanation
- Characteristic 3: Brief explanation
## How it works
Detailed explanation of mechanics, with diagrams if helpful.
## Related concepts
- [Related Concept 1](link) – Brief connection explanation
- [Related Concept 2](link) – Brief connection explanation
Example (from Accounts documentation):
In banking terms, an Account represents a financial product, such as a checking account, savings account, or loan account.
2. Getting Started Guides
Helps users accomplish their first task with the product.
Structure:
# Getting started with [Feature]
Brief intro explaining what users will accomplish.
## Prerequisites
- Requirement 1
- Requirement 2
## Step 1: First action
Explanation of what to do and why.
[Code example or screenshot]
## Step 2: Second action
Continue the workflow.
## Next steps
- [Advanced topic 1](link)
- [Advanced topic 2](link)
3. How-To Guides
Task-focused documentation for specific goals.
Structure:
# How to [accomplish task]
Brief context on when and why you'd do this.
## Before you begin
Prerequisites or context needed.
## Steps
1. **Action name**: Description of what to do
2. **Action name**: Description of what to do
3. **Action name**: Description of what to do
## Verification
How to confirm success.
## Troubleshooting
Common issues and solutions.
4. Best Practices
Guidance on optimal usage patterns.
Structure:
# Best practices for [topic]
Brief intro on why these practices matter.
## Practice 1: Name
- **Mistake:** What users commonly do wrong
- **Best practice:** What to do instead and why
## Practice 2: Name
- **Mistake:** Common error pattern
- **Best practice:** Correct approach
## Summary
Key takeaways in bullet form.
Writing Patterns
Lead with Value
Start every document with a clear statement of what the reader will learn or accomplish.
Good:
This guide shows you how to create your first transaction in under 5 minutes.
Avoid:
In this document, we will discuss the various aspects of transaction creation.
Use Second Person ("You")
Address the reader directly.
Good:
You can create as many accounts as your structure demands.
Avoid:
Users can create as many accounts as their structure demands.
Present Tense
Use present tense for current behavior.
Good:
Midaz uses a microservices architecture.
Avoid:
Midaz will use a microservices architecture.
Action-Oriented Headings
Headings should indicate what the section covers or what users will do.
Good:
Creating your first account
Avoid:
Account creation process overview
Short Paragraphs
Keep paragraphs to 2-3 sentences maximum. Use bullet points for lists.
Good:
Each Account is linked to exactly one Asset type. Accounts are uniquely identified within a Ledger.
Avoid:
Each Account is linked to exactly one Asset type, and accounts are uniquely identified within a Ledger, which tracks and consolidates all balances and operations for the organization.
Visual Elements
Info Boxes
Use for helpful tips or additional context.
> **Tip:** You can use account aliases to make transactions more readable.
Warning Boxes
Use for important cautions.
> **Warning:** External accounts cannot be deleted or changed.
Code Examples
Always include working examples for technical concepts.
```json
{
"name": "Customer Account",
"assetCode": "BRL",
"type": "checking"
}
### Tables
Use for comparing options or showing structured data.
```markdown
| Option | When to Use |
|--------|-------------|
| Community | Developers, startups, experimentation |
| Enterprise | Production, compliance, dedicated support |
Section Dividers
Use horizontal rules (---) to separate major sections. This improves scannability.
## Section One
Content here.
---
## Section Two
Content here.
Linking Patterns
Internal Links
Link to related documentation when mentioning concepts.
Good:
Each Account is linked to a single Asset, defining the type of value it holds.
API Reference Links
Connect functional docs to API reference.
Good:
You can manage your Accounts via API or through the Console.
Next Steps
End guides with clear next steps.
## Next steps
- [Learn about Portfolios](link) – Group accounts for easier management
- [Create your first Transaction](link) – Move funds between accounts
Quality Checklist
Before finishing functional documentation, verify:
- Leads with clear value statement
- Uses second person ("you")
- Uses present tense
- Headings are action-oriented (sentence case)
- Paragraphs are short (2-3 sentences)
- Includes working code examples
- Links to related documentation
- Ends with next steps
- Follows voice and tone guidelines