documentation-writing
Creates clear, accessible documentation and communications for diverse audiences. Use when: writing guides, creating documentation, drafting communications, or synthesizing complex information for technical and non-technical audiences.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- documentation-writing
- owner
- pm
- scope
- common
- status
- active
- version
- 1.0.3
- metadata
- { "type": "implementation", "triggers": [ "write documentation", "create guide", "draft communication", "write manual", "create tutorial", "documentation", "technical writing" ] }
- relates_to
- [ { "type": "composes_with", "skill": "team-builder" } ]
- description
- Creates clear, accessible documentation and communications for diverse audiences. Use when: writing guides, creating documentation, drafting communications, or synthesizing complex information for technical and non-technical audiences.
- gemini-parity
- skip
- last_reviewed
- 1794096000000
- prerequisites
- none
03 SKILL.md 正文
Context
This skill provides comprehensive documentation writing capabilities, from technical guides to user-friendly manuals. It ensures documentation is clear, well-structured, accessible, and appropriately targeted to the intended audience.
When to Use
Technical Documentation:
- Trigger: "Write technical documentation" or "Create API reference"
- Use Case: Documenting technical systems, APIs, or code
User Guides:
- Trigger: "Create user guide" or "Write manual"
- Use Case: Helping end users understand and use products or features
Process Documentation:
- Trigger: "Document process" or "Create workflow guide"
- Use Case: Explaining how to complete tasks or procedures
Communications:
- Trigger: "Draft announcement" or "Write communication"
- Use Case: Sharing information with stakeholders or teams
Execution Steps
Step 1: Audience Analysis
Purpose: Understand who will read the documentation and their needs.
Audience Assessment:
-
Technical Level:
- Technical experts (developers, engineers)
- Technical users (power users, administrators)
- Non-technical users (end users, general audience)
- Mixed audiences
-
Knowledge Base:
- What prior knowledge do they have?
- What terminology will they understand?
- What concepts need explanation?
- What examples will resonate?
-
Use Context:
- When will they use this documentation?
- What problem are they trying to solve?
- What's their urgency or stress level?
- What format do they prefer?
-
Accessibility Needs:
- Language requirements (English, Korean, multi-language)
- Reading level considerations
- Format preferences (visual, text, interactive)
- Disability accommodations
Korean Plain-Language Preference (순우리말-first): when the deliverable is Korean, prefer native Korean words over loanwords where a natural, widely-understood equivalent exists (e.g. 만들기 over 크리에이션, 알림 over 노티피케이션). Settled loanwords (컴퓨터, 데이터, 소프트웨어, 파일) and established technical terms remain permitted — clarity and standard terminology take precedence. When editing existing Korean documents for other reasons, nativize the touched sections incrementally; no bulk rewrites.
Output: Audience profile with characteristics and needs
Step 2: Information Architecture
Purpose: Structure documentation for clarity and navigation.
Structuring Principles:
-
Hierarchical Organization:
- Overview → Details → Reference
- High-level concepts → Specific tasks
- General information → Edge cases
-
Progressive Disclosure:
- Start with essentials
- Reveal complexity gradually
- Link to detailed information
- Provide multiple depth levels
-
Logical Flow:
- Chronological (step-by-step processes)
- Task-based (common user goals)
- Conceptual (building understanding)
- Reference (alphabetical, searchable)
-
Navigation Design:
- Table of contents
- Section headers and subheaders
- Cross-references and links
- Index or search keywords
Common Documentation Structures:
- Getting Started Guide: Setup → First steps → Common tasks
- User Manual: Overview → Features → Instructions → Reference
- Technical Guide: Architecture → Implementation → API → Examples
- Troubleshooting: Symptoms → Causes → Solutions → Prevention
Output: Documentation outline with structure and flow
Step 3: Content Creation
Purpose: Write clear, actionable content.
Writing Principles:
-
Clarity First:
- Use simple, direct language
- One idea per sentence
- Active voice over passive
- Specific over general
-
Accessibility:
- Define technical terms on first use
- Provide examples and analogies
- Use visual aids (diagrams, screenshots)
- Consider non-native speakers
-
Actionability:
- Start with verbs for instructions
- Provide step-by-step procedures
- Include expected results
- Add troubleshooting guidance
-
Scannability:
- Use bullet points and lists
- Highlight important information
- Break text into short paragraphs
- Use descriptive headers
Content Types:
-
Procedural Content:
- Step-by-step instructions
- Numbered lists for sequences
- Conditional steps (if/then)
- Warnings and cautions
-
Conceptual Content:
- Explanations and definitions
- Examples and use cases
- Diagrams and illustrations
- Analogies and comparisons
-
Reference Content:
- Tables and matrices
- Code examples and snippets
- Configuration options
- Error messages and solutions
Output: Complete documentation content with clear structure
Step 4: Visual Communication
Purpose: Enhance understanding with visual elements.
Visual Design Guidelines:
-
Diagrams and Flowcharts:
- Use for processes and workflows
- Keep simple and focused
- Label all elements clearly
- Include legends if needed
-
Screenshots and Images:
- Show actual interface elements
- Highlight important areas
- Add annotations and callouts
- Maintain consistent style
-
Tables and Charts:
- Organize complex information
- Use clear headers and labels
- Highlight key data points
- Provide context and interpretation
-
Code Examples:
- Show working examples
- Add comments explaining code
- Use syntax highlighting
- Include expected output
Visual Accessibility:
- Provide text alternatives (alt text)
- Ensure sufficient color contrast
- Use readable fonts and sizes
- Consider color blindness
Output: Visual elements that enhance understanding
Step 5: Review and Refine
Purpose: Ensure documentation meets quality standards.
Quality Checklist:
- [ ] Content is accurate and complete
- [ ] Structure is logical and navigable
- [ ] Language is clear and accessible
- [ ] Examples are relevant and helpful
- [ ] Visual aids support understanding
- [ ] Formatting is consistent
- [ ] Cross-references work correctly
- [ ] Technical terms are defined
- [ ] Instructions are actionable
- [ ] Troubleshooting covers common issues
Testing Methods:
-
Usability Testing:
- Have users follow documentation
- Observe where they get stuck
- Ask for feedback on clarity
- Test with diverse users
-
Technical Review:
- Subject matter expert review
- Technical accuracy verification
- Completeness check
- Edge case coverage
-
Editorial Review:
- Grammar and spelling check
- Style guide consistency
- Formatting verification
- Link testing
Output: Refined documentation with quality assurance
Step 6: Publishing and Maintenance
Purpose: Make documentation available and keep it current.
Publishing Considerations:
-
Format Selection:
- Markdown (for version control and collaboration)
- HTML (for web publishing)
- PDF (for offline reading and printing)
- Interactive (for tutorials and guides)
-
Distribution:
- Documentation sites (GitBook, ReadTheDocs)
- Wikis and knowledge bases
- Inline help and tooltips
- Print manuals
-
Version Control:
- Track documentation versions
- Maintain change logs
- Archive outdated versions
- Tag documentation releases
-
Maintenance:
- Review schedule (quarterly, per release)
- Update procedures
- Feedback collection
- Accuracy verification
Maintenance Tasks:
- Update for product changes
- Revise based on user feedback
- Add new FAQs and troubleshooting
- Remove or archive outdated content
- Update screenshots and examples
Output: Published documentation with maintenance plan
Output Format
For Technical Documentation:
- API references with parameters and responses
- Architecture documentation with diagrams
- Setup and installation guides
- Configuration references
- Troubleshooting guides
For User Documentation:
- Getting started guides
- Feature explanations
- How-to tutorials
- FAQ sections
- Best practices guides
For Process Documentation:
- Workflow descriptions
- Procedure manuals
- Training materials
- Onboarding guides
- Standard operating procedures
Best Practices
Writing Quality: ✅ Do:
- Write for your specific audience
- Use simple, direct language
- Provide examples and context
- Include visual aids
- Test with actual users
- Update regularly
❌ Don't:
- Assume prior knowledge
- Use jargon without explanation
- Create walls of text
- Skip visual formatting
- Write for "everyone" (be specific)
- Set and forget documentation
Structure Quality: ✅ Do:
- Start with overview
- Use progressive disclosure
- Provide multiple navigation paths
- Include cross-references
- Add search keywords
- Create scannable content
❌ Don't:
- Bury important information
- Create deep hierarchies
- Make users read everything
- Use ambiguous headers
- Ignore different learning styles
- Write monolithic documents
Common Mistakes to Avoid
Content Anti-Patterns:
- Information Dump: Including everything without organization
- Assumption Trap: Assuming reader knows what you know
- Tone Mismatch: Too formal or too casual for audience
- Update Neglect: Letting documentation become outdated
- Missing Context: Focusing on what without explaining why
Structure Anti-Patterns:
- Poor Organization: Illogical flow or grouping
- Navigation Fail: Difficult to find specific information
- Inconsistency: Different styles or formats in same doc
- Gaps: Missing steps or important information
- Overcompleteness: Including unnecessary detail
Related Skills
- research-analysis: For gathering information to document
- technical-writing: For specialized technical documentation
- accessibility-review: For ensuring documentation accessibility
- visual-design: For creating effective diagrams and visual aids
Documentation Tools
Authoring Tools:
- Markdown editors (Typora, VS Code, Obsidian)
- Documentation generators (Jekyll, Hugo, Docusaurus)
- Wiki platforms (Confluence, Notion, GitBook)
- Content management systems
Collaboration Tools:
- Version control (Git)
- Review tools (GitHub PRs, Google Docs comments)
- Style guides (Google Developer Documentation Style Guide)
- Editorial calendars
Publishing Platforms:
- Static site generators (MkDocs, Docusaurus)
- Documentation hosting (GitBook, ReadTheDocs)
- Knowledge bases (Confluence, Notion)
- Versioned documentation (Git-backed)
Quality Tools:
- Grammar checkers (Grammarly, LanguageTool)
- Link checkers (broken link detectors)
- SEO tools (for public documentation)
- Analytics (user engagement tracking)
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.