majiayu000 Feature Documentation Skill
Diátaxis Framework
This skill supports three documentation types. When creating a NEW document, ask the user which type they need:
| Type | Template | Purpose | Audience |
|---|---|---|---|
| Tutorial | templates/tutorial.md |
Learning-focused, step-by-step guide | Beginners |
| How-To | templates/how-to.md |
Task-focused, solve specific problems | Developers |
| Reference | templates/reference.md |
Technical specs, API docs | Developers |
Note: For admin/non-technical users, use the
document-admin-guideskill instead.
Smart Interaction
ASK the User When:
- Creating new doc: Confirm doc type (Tutorial/How-To/Reference), audience, and output location
- Deleting a doc: Always confirm before deletion
- Major restructure: Moving multiple docs or changing navigation
- Ambiguous request: Can't determine intent from context
PROCEED Autonomously When:
- Updating existing doc: Use best judgment, preserve existing structure
- Adding content: Follow existing template/format
- Fixing errors/typos: Non-destructive improvements
- Adding diagrams: Enhancement to existing doc
- Updating code examples: Keep docs in sync with codebase
Instructions
When documenting a feature:
- Determine doc type - Ask user if creating new doc; infer from existing if updating
- Explore the codebase to find all related files for this feature
- Use the appropriate template from
templates/folder - Generate Mermaid diagrams for architecture (C4 style)
- Include real code examples from the codebase (not hypothetical)
- Check for existing ADRs in
/docs/decisions/related to this feature - Output to appropriate location based on doc type
Output Locations
| Doc Type | Output Path |
|---|---|
| Tutorial | /docs/getting-started/[feature-name].md |
| How-To | /docs/developer-guide/[task-name].md |
| Reference | /docs/reference/[component-name].md |
Templates
All templates are located in .claude/skills/document-feature/templates/:
- tutorial.md - For learning-focused beginner guides
- how-to.md - For task-focused developer guides
- reference.md - For API/component technical reference
Diagram Standards
- Use Mermaid for all diagrams
- C4-style naming: System, Container, Component
- Sequence diagrams for data flows
- Include legends for complex diagrams
Quality Checklist
Before completing:
- Correct template used for doc type
- At least one architecture diagram (if applicable)
- Real code examples from codebase
- File paths verified to exist
- Links to related docs included
- Prerequisites section included (for tutorials/how-tos)
Examples
Creating New Docs (Will Ask User)
- "Document the search feature" → Ask: Tutorial, How-To, or Reference?
- "Create docs for Excel import" → Ask: What type and audience?
Updating Existing Docs (Autonomous)
- "Update the search docs with new API endpoint" → Updates existing doc
- "Add error handling examples to API reference" → Adds to existing doc
- "Fix outdated code example in tutorial" → Fixes without asking
Routing by Request Type
- "Help new devs understand search" → Tutorial
- "How to implement search filtering" → How-To
- "Document the search API" → Reference