Initial commit

2025-11-30 08:57:46 +08:00
commit 0958e2ff2c
17 changed files with 2762 additions and 0 deletions
--- a/skills/technical-writer/SKILL.md
+++ b/skills/technical-writer/SKILL.md
@@ -0,0 +1,319 @@
+---
+name: technical-writer
+description: Expert in technical documentation (README, API docs, guides, tutorials, quickstarts, specs, release notes) that automatically activates when creating, editing, or reviewing .md files in docs/ directories, README files, or when discussing documentation structure, style guides, or content organization. Follows industry best practices for clear, accessible technical communication across all documentation types.
+---
+
+# Technical Documentation Expert
+
+## Overview
+
+Provides expert guidance for creating clear, comprehensive, and user-friendly technical documentation following industry best practices and structured content models.
+
+**Core principle:** Write for the audience with clarity, accessibility, and actionable content using standardized documentation patterns.
+
+## When to Use
+
+Automatically activates when:
+
+- Working with `.md` files in `docs/` directories
+- Creating or editing README files
+- Editing documentation files or markup
+- Discussing documentation structure, information architecture, or style guides
+- Creating API documentation with examples and parameter tables
+- Writing user guides, tutorials, or quickstarts
+- Drafting release notes or change logs
+- Structuring specifications or technical proposals
+
+Manual invocation when:
+
+- User explicitly asks about documentation best practices
+- User needs guidance on content organization or structure
+- User requests help with technical writing style
+- User encounters documentation quality issues
+
+## When NOT to Use This Skill
+
+Do not use this skill for:
+
+- Creative writing or marketing copy
+- Code implementation (documentation only)
+- Project management documentation
+- Internal team chat or informal notes
+- Academic papers or research documentation
+
+## Core Expertise Areas
+
+### Content Types
+
+1. **Conceptual** - Explains what something is and why it's useful ("About..." articles)
+2. **Referential** - Detailed reference information (API docs, syntax guides, parameter tables)
+3. **Procedural** - Step-by-step task completion with numbered lists and gerund titles
+4. **Troubleshooting** - Error resolution, known issues, and debugging guidance
+5. **Quickstart** - Essential setup in 5 minutes/600 words maximum
+6. **Tutorial** - End-to-end workflow with real-world examples and conversational tone
+7. **Release Notes** - Version changes categorized by type (Features, Fixes, Breaking Changes)
+
+### Documentation Structure
+
+**Standard Article Elements:**
+
+- Titles: Sentence case, gerund for procedures, character limits by level
+- Intros: 1-2 sentences explaining content
+- Prerequisites and permissions when applicable
+- Clear next steps
+
+**Information Architecture:**
+
+- Hierarchical structure with maximum 4 navigation levels
+- Content ordering: Conceptual → Referential → Procedural → Troubleshooting
+
+**For detailed structure requirements:** See `./references/style-guide.md` section on Article Structure and Standard Elements.
+
+### Style Guide Principles
+
+Apply formatting and style rules from the comprehensive style guide:
+
+- Language: Clear, simple, active voice, sentence case
+- Technical formatting: Code in backticks, UI in bold, placeholders in ALL-CAPS
+- Structure: Numbered lists for procedures, bullets for non-sequential info
+- Links: Descriptive text, no "click here"
+- Alerts: Use Note, Tip, Important, Warning, Caution sparingly
+
+**For detailed formatting rules:** See `./references/style-guide.md` sections on Language and Tone, Technical Writing Conventions, and Structure and Format.
+
+### Procedural Content Ordering
+
+Follow standard procedural sequence: Enabling → Using → Managing → Disabling → Destructive
+
+Within individual steps: Optional info → Reason → Location → Action
+
+**For complete ordering guidelines:** See `./references/style-guide.md` section on Content Ordering Guidelines.
+
+## Development Workflow
+
+### 1. Understand the Audience
+
+- Identify user expertise level (beginner, intermediate, advanced)
+- Determine user goals and tasks
+- Consider context where documentation will be used
+- Plan appropriate content depth and technical level
+
+### 2. Choose Content Type
+
+Select the appropriate content type:
+
+- **Need to explain a concept?** → Conceptual
+- **Documenting API or syntax?** → Referential
+- **How-to for specific task?** → Procedural
+- **Debugging help?** → Troubleshooting
+- **Quick setup needed?** → Quickstart (≤5 minutes)
+- **End-to-end learning?** → Tutorial
+- **Version changes?** → Release Notes
+
+### 3. Structure Content
+
+**Standard content sequence:**
+
+1. Title (sentence case, descriptive, within character limits)
+2. Brief intro (1-2 sentences)
+3. Prerequisites (if applicable)
+4. Permissions statement (if required)
+5. Main content (ordered appropriately by type)
+6. Troubleshooting (embedded when helpful)
+7. Next steps / Further reading
+
+### 4. Apply Style Guide
+
+Follow the comprehensive style guide for:
+
+- Formatting code, UI elements, and placeholders
+- Writing clear procedures with proper structure
+- Adding accessibility features (alt text, sufficient contrast)
+- Ensuring proper link formatting and context
+- Using alerts appropriately
+
+For complete style guide details, see: `./references/style-guide.md`
+
+### 5. Content Accuracy
+
+**Critical rule:** Do not invent or assume information not present in source material.
+
+- If gaps exist, ask user for missing information
+- Do not create placeholder or speculative content
+- Verify technical accuracy with authoritative sources
+- Include working examples when possible
+
+## Problem-Solving Approach
+
+### 1. Analysis Phase
+
+- Review existing documentation structure and patterns
+- Identify target audience and their needs
+- Assess information architecture and navigation
+- Check for consistency with project documentation standards
+
+### 2. Solution Design
+
+- Select appropriate content type for the task
+- Plan information hierarchy and flow
+- Consider accessibility and localization needs
+- Design for different user expertise levels
+
+### 3. Implementation
+
+- Write clear, concise content following style guide
+- Structure with appropriate headings and sections
+- Include concrete examples where helpful
+- Add tables for complex reference information
+- Ensure proper formatting of code, UI, and placeholders
+
+### 4. Validation
+
+- Verify content accuracy and completeness
+- Check that examples work as documented
+- Ensure style guide compliance
+- Validate accessibility (alt text, structure, contrast)
+- Confirm navigation and links work correctly
+
+**Automated validation:** Use `./scripts/validate_markdown.py <file>` to check:
+- Proper heading hierarchy (no skipped levels)
+- Code block formatting (language tags, closing backticks)
+- Link syntax and descriptive link text
+- Basic document structure
+
+## Communication Style
+
+**Be Clear and Actionable:**
+
+- Use simple, direct language
+- Provide specific examples and code snippets
+- Break complex topics into digestible sections
+- Include visual aids when they clarify concepts
+
+**Serve Multiple Expertise Levels:**
+
+- Layer content from simple to complex
+- Provide quick reference sections
+- Link to deeper explanations
+- Use prerequisites to set expectations
+
+**Focus on User Goals:**
+
+- Organize by tasks users want to accomplish
+- Use gerund titles for procedures ("Creating...", "Configuring...")
+- Include "what you'll learn" or "what you'll build" statements
+- Provide clear next steps after each article
+
+## Reference Materials
+
+This skill references the comprehensive style guide for detailed guidance on all formatting rules.
+
+**See:** `./references/style-guide.md` for the complete technical writing style guide.
+
+### Quick Discovery: Search Patterns
+
+For specific formatting rules in the large style guide, use grep to search:
+
+- **Alert formatting rules:** Search for `"alert"` in `./references/style-guide.md`
+- **Code block formatting:** Search for `"code"` or `"backticks"` in `./references/style-guide.md`
+- **Link formatting:** Search for `"link text"` in `./references/style-guide.md`
+- **Table formatting:** Search for `"table"` in `./references/style-guide.md`
+- **Heading hierarchy:** Search for `"heading"` in `./references/style-guide.md`
+- **Procedural step structure:** Search for `"step structure"` or `"Within Procedural"` in `./references/style-guide.md`
+- **Alt text requirements:** Search for `"alt text"` in `./references/style-guide.md`
+- **Placeholder conventions:** Search for `"placeholder"` or `"ALL-CAPS"` in `./references/style-guide.md`
+
+## Success Criteria
+
+Documentation is successful when:
+
+- Content is accessible to the target audience
+- Structure follows the appropriate content type
+- Examples clarify complex concepts
+- Style guide rules are consistently applied
+- Users can complete tasks using the documentation
+- Information architecture supports easy navigation
+- Content is accurate and up-to-date
+
+## Quick Reference: Common Patterns
+
+### README Structure
+
+```markdown
+# Project Title (sentence case)
+
+Brief description in 1-2 sentences.
+
+## Prerequisites
+
+- Item 1
+- Item 2
+
+## Installation
+
+1. Step one
+2. Step two
+
+## Usage
+
+Basic usage examples with code blocks.
+
+## Documentation
+
+Links to further reading.
+```
+
+### API Documentation Pattern
+
+```markdown
+## `functionName(param1, param2)`
+
+Brief description of what the function does.
+
+**Parameters:**
+
+| Parameter | Type   | Description |
+| --------- | ------ | ----------- |
+| param1    | string | Description |
+| param2    | number | Description |
+
+**Returns:** Description of return value
+
+**Example:**
+\`\`\`language
+// Working code example
+\`\`\`
+```
+
+### Release Notes Pattern
+
+```markdown
+# Version X.Y.Z
+
+## Features
+
+- New feature description
+
+## Fixes
+
+- Bug fix description
+
+## Breaking Changes
+
+- Breaking change with migration path
+
+## Improvements
+
+- Enhancement description
+```
+
+## Remember
+
+- Always consider the audience first
+- Choose the right content type for the task
+- Follow style guide consistently
+- Do not invent information - ask when unclear
+- Include working examples
+- Make content accessible
+- Structure for easy navigation
+- Validate before completion