Initial commit

skills/writing-functional-docs/SKILL.md

@@ -0,0 +1,306 @@
+---
+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