Initial commit

2025-11-30 08:37:25 +08:00
commit 71961f9eff
18 changed files with 3314 additions and 0 deletions
--- a/skills/documentation-structure/SKILL.md
+++ b/skills/documentation-structure/SKILL.md
@@ -0,0 +1,342 @@
+---
+name: documentation-structure
+description: |
+  Patterns for organizing and structuring documentation including hierarchy,
+  navigation, and information architecture.
+
+trigger: |
+  - Planning documentation structure
+  - Organizing content hierarchy
+  - Deciding how to split content across pages
+  - Creating navigation patterns
+
+skip_when: |
+  - Writing content → use writing-functional-docs or writing-api-docs
+  - Checking voice → use voice-and-tone
+
+related:
+  complementary: [writing-functional-docs, writing-api-docs]
+---
+
+# Documentation Structure
+
+Good structure helps users find what they need quickly. Organize content by user tasks and mental models, not by internal system organization.
+
+---
+
+## Content Hierarchy
+
+### Top-Level Organization
+
+Structure documentation around user needs:
+
+```
+Documentation/
+├── Welcome/              # Entry point, product overview
+├── Getting Started/      # First steps, quick wins
+├── Guides/              # Task-oriented documentation
+│   ├── Understanding X   # Conceptual documentation
+│   ├── Installing X     # Setup and deployment
+│   ├── Use Cases        # Real-world scenarios
+│   ├── Core Entities    # Domain concepts
+│   └── Best Practices   # Recommendations
+├── API Reference/       # Technical reference
+│   ├── Introduction     # API overview
+│   ├── Getting Started  # Quick start
+│   └── Endpoints/       # Per-resource documentation
+└── Updates/             # Changelog, versioning
+```
+
+---
+
+## Page Structure Patterns
+
+### Overview Pages
+Introduce a section and link to child pages.
+
+```markdown
+# Section Name
+
+Brief description of what this section covers and who it's for.
+
+---
+
+## Content
+
+In this section, you will find:
+
+- [**Topic A**](link): Brief description
+- [**Topic B**](link): Brief description
+- [**Topic C**](link): Brief description
+```
+
+---
+
+### Conceptual Pages
+Explain a single concept thoroughly.
+
+```markdown
+# Concept Name
+
+Lead paragraph defining the concept and its importance.
+
+## Key characteristics
+
+- Point 1
+- Point 2
+- Point 3
+
+## How it works
+
+Detailed explanation with diagrams.
+
+---
+
+## Subtopic A
+
+Content about subtopic A.
+
+---
+
+## Subtopic B
+
+Content about subtopic B.
+
+---
+
+## Related concepts
+
+- [Related A](link) – Connection explanation
+- [Related B](link) – Connection explanation
+```
+
+---
+
+### Task-Oriented Pages
+Guide users through a specific workflow.
+
+```markdown
+# How to [accomplish task]
+
+Brief context on when and why.
+
+## Prerequisites
+
+- Requirement 1
+- Requirement 2
+
+---
+
+## Step 1: Action name
+
+Explanation of what to do.
+
+## Step 2: Action name
+
+Continue the workflow.
+
+---
+
+## Verification
+
+How to confirm success.
+
+## Next steps
+
+- [Follow-up task](link)
+- [Related task](link)
+```
+
+---
+
+## Section Dividers
+
+Use horizontal rules (`---`) to create visual separation between major sections.
+
+```markdown
+## Section One
+
+Content here.
+
+---
+
+## Section Two
+
+New topic content here.
+```
+
+**When to use dividers:**
+- Between major topic changes
+- Before "Related" or "Next steps" sections
+- After introductory content
+- Before prerequisites in guides
+
+**Don't overuse:** Not every heading needs a divider. Use them for significant transitions.
+
+---
+
+## Navigation Patterns
+
+### Breadcrumb Context
+Always show where users are in the hierarchy:
+
+```
+Guides > Core Entities > Accounts
+```
+
+### Previous/Next Links
+Connect sequential content:
+
+```markdown
+[Previous: Assets](link) | [Next: Portfolios](link)
+```
+
+### On-This-Page Navigation
+For long pages, show section links:
+
+```markdown
+On this page:
+- [Key characteristics](#key-characteristics)
+- [How it works](#how-it-works)
+- [Managing via API](#managing-via-api)
+```
+
+---
+
+## Information Density
+
+### Scannable Content
+Users scan before they read. Make content scannable:
+
+1. **Lead with the key point** in each section
+2. **Use bullet points** for lists of 3+ items
+3. **Use tables** for comparing options
+4. **Use headings** every 2-3 paragraphs
+5. **Use bold** for key terms on first use
+
+---
+
+### Progressive Disclosure
+
+Start with essentials, then add depth:
+
+```markdown
+# Feature Overview
+
+Essential information that 80% of users need.
+
+---
+
+## Advanced Configuration
+
+Deeper details for users who need them.
+
+### Rare Scenarios
+
+Edge cases and special situations.
+```
+
+---
+
+## Tables vs Lists
+
+### Use Tables When:
+- Comparing multiple items across same attributes
+- Showing structured data (API fields, parameters)
+- Displaying options with consistent properties
+
+```markdown
+| Model | Best For | Support Level |
+|-------|----------|---------------|
+| Community | Experimentation | Community |
+| Enterprise | Production | Dedicated |
+```
+
+### Use Lists When:
+- Items don't have comparable attributes
+- Sequence matters (steps)
+- Items have varying levels of detail
+
+```markdown
+## Key features
+
+- **Central Ledger**: Real-time account and transaction management
+- **Modularity**: Flexible architecture for customization
+- **Scalability**: Handles large transaction volumes
+```
+
+---
+
+## Code Examples Placement
+
+### Inline Code
+For short references within text:
+
+> Set the `assetCode` field to your currency code.
+
+### Code Blocks
+For complete, runnable examples:
+
+```json
+{
+  "name": "Customer Account",
+  "assetCode": "BRL"
+}
+```
+
+### Placement Rules:
+1. Show the example immediately after explaining it
+2. Keep examples minimal but complete
+3. Use realistic data (not "foo", "bar")
+4. Show both request and response for API docs
+
+---
+
+## Cross-Linking Strategy
+
+### Link to First Mention
+Link concepts when first mentioned in a section:
+
+> Each [Account](link) is linked to a single [Asset](link).
+
+### Don't Over-Link
+Don't link every mention of a term. Once per section is enough.
+
+### Link Destinations
+
+| Link Type | Destination |
+|-----------|-------------|
+| Concept name | Conceptual documentation |
+| API action | API reference endpoint |
+| "Learn more" | Deeper dive documentation |
+| "See also" | Related but different topics |
+
+---
+
+## Page Length Guidelines
+
+| Page Type | Target Length | Reasoning |
+|-----------|---------------|-----------|
+| Overview | 1-2 screens | Quick orientation |
+| Concept | 2-4 screens | Thorough explanation |
+| How-to | 1-3 screens | Task completion |
+| API endpoint | 2-3 screens | Complete reference |
+| Best practices | 3-5 screens | Multiple recommendations |
+
+If a page exceeds 5 screens, consider splitting into multiple pages.
+
+---
+
+## Quality Checklist
+
+Before finalizing structure:
+
+- [ ] Content is organized by user task, not system structure
+- [ ] Overview pages link to all child content
+- [ ] Section dividers separate major topics
+- [ ] Headings create scannable structure
+- [ ] Tables are used for comparable items
+- [ ] Code examples follow explanations
+- [ ] Cross-links connect related content
+- [ ] Page length is appropriate for content type
+- [ ] Navigation (prev/next) connects sequential content