307 lines
6.2 KiB
Markdown
307 lines
6.2 KiB
Markdown
---
|
||
name: writing-functional-docs
|
||
description: |
|
||
Patterns and structure for writing functional documentation including guides,
|
||
conceptual explanations, tutorials, and best practices documentation.
|
||
|
||
trigger: |
|
||
- Writing a new guide or tutorial
|
||
- Creating conceptual documentation
|
||
- Documenting best practices
|
||
- Writing "how to" content
|
||
|
||
skip_when: |
|
||
- Writing API reference → use writing-api-docs
|
||
- Reviewing documentation → use documentation-review
|
||
- Writing code → use dev-team agents
|
||
|
||
sequence:
|
||
before: [documentation-review]
|
||
|
||
related:
|
||
similar: [writing-api-docs]
|
||
complementary: [voice-and-tone, documentation-structure]
|
||
---
|
||
|
||
# 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:**
|
||
```markdown
|
||
# 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:**
|
||
```markdown
|
||
# 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:**
|
||
```markdown
|
||
# 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:**
|
||
```markdown
|
||
# 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.
|
||
|
||
```markdown
|
||
> **Tip:** You can use account aliases to make transactions more readable.
|
||
```
|
||
|
||
### Warning Boxes
|
||
Use for important cautions.
|
||
|
||
```markdown
|
||
> **Warning:** External accounts cannot be deleted or changed.
|
||
```
|
||
|
||
### Code Examples
|
||
Always include working examples for technical concepts.
|
||
|
||
```markdown
|
||
```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.
|
||
|
||
```markdown
|
||
## 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](link-to-assets), defining the type of value it holds.
|
||
|
||
### API Reference Links
|
||
Connect functional docs to API reference.
|
||
|
||
**Good:**
|
||
> You can manage your Accounts via [API](link) or through the [Console](link).
|
||
|
||
### Next Steps
|
||
End guides with clear next steps.
|
||
|
||
```markdown
|
||
## 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
|