Documentation Preparation Skill (Automated Workflow - Step 1)

Overview

This skill prepares complete documentation requirements for automated generation. It:

•Discovers all sources - Core sources + related files (tests, types, examples)
•Defines document structure - Based on doc type and project templates
•Builds content map - What to document from where
•Saves requirements file - Complete specification for write-docs skill

When to use this skill:

•User says "문서 준비해줘" or "prepare documentation"
•Starting automated documentation workflow
•User wants hands-off doc generation after initial setup

⚠️ IMPORTANT - Automated Workflow:

•Interactive setup - Steps 1-3 ask user questions to define scope
•Automated discovery - Step 4 automatically finds related sources and builds content map
•Saves requirements to file - Always outputs docs/doc-requirements.md

Workflow: 5-Step Preparation Process

Step 1: Collect Source Links

Questions to ask:

•
"어떤 소스를 분석할까요?" (What sources should I analyze?)
- •GitHub repositories (URLs or local paths)
- •Web pages (documentation sites, blog posts)
- •Local files (code files, markdown docs, PDFs)
- •Google Drive documents (check for MCP server)
- •Notion pages (check for MCP server)
•
"중점적으로 분석할 키워드나 토픽이 있나요?" (Any specific keywords or topics to focus on?)

Step 2: Select Document Type

Ask: "어떤 문서를 만들까요?" (What type of documentation should I create?)

Options:

•
API Reference
- •Audience: Developers integrating with the code
- •Focus: Functions, classes, parameters, return values, examples
- •Structure: Organized by module/class/function
•
System Overview
- •Audience: Engineers understanding architecture
- •Focus: Components, data flow, design principles, communication patterns
- •Structure: Top-down from high-level to implementation details
•
Tutorial
- •Audience: Users learning how to use the system
- •Focus: Step-by-step instructions, practical examples, common pitfalls
- •Structure: Sequential steps with verification checkpoints
•
Custom
- •User specifies their own document type and purpose

Step 3: Define Document Structure

Based on document type selected in Step 2, present default sections and ask user to customize.

Workflow:

•
Show default sections for selected document type (see below)
•
Ask user: "기본 구조에서 제외할 항목이 있나요?" (Any sections to remove from default structure?)
- •User can specify sections to exclude
- •Example: "Performance Characteristics 제외"
•
Ask user: "추가로 포함할 항목이 있나요?" (Any additional sections to include?)
- •User can add custom sections
- •Examples: Migration Guide, Troubleshooting, FAQ, Benchmarks, Comparison with Alternatives
•
Confirm final structure - Show final section list before proceeding to Step 4

Note: If user mentions a project template, use that instead of default structure.

Default sections by document type:

For API Reference:

For System Overview:

• Introduction (purpose, use cases)
• Architecture (high-level design)
• Components (individual parts + responsibilities)
• Data Flow (how information moves)
• State Management
• Communication Patterns
• Configuration
• Error Handling
• Performance Characteristics

For Tutorial:

• Introduction (what you'll learn, time estimate)
• Prerequisites (required knowledge, tools)
• Step 1, 2, 3... (sequential instructions)
• Testing Your Implementation
• Common Pitfalls
• Next Steps

Note: Order sections logically (general → specific) in final structure.

Step 4: Content Discovery and Source Expansion

Purpose: Start from core sources and actively discover all related sources needed for comprehensive documentation.

Workflow:

•
Analyze core sources (from Step 1)
- •Identify documentable items: functions, types, classes, concepts
- •Note primary information available
•
For each item, discover related sources:

For Functions/Methods:
- •✅ Test files (usage examples, edge cases)
- •✅ Type definitions (parameter types, return types)
- •✅ Related functions (callers, callees)
- •✅ Documentation comments (inline docs)
- •✅ Error handling (related error types)
For Types/Classes:
- •✅ Constructors and factory functions
- •✅ Methods and properties
- •✅ Usage examples in tests
- •✅ Related types (inheritance, composition)
- •✅ Serialization/deserialization code
For Concepts/Modules:
- •✅ Design documents (docs/, wiki, ADRs)
- •✅ README files
- •✅ Example code (examples/, demos/)
- •✅ Related modules (imports, dependencies)

•

Build content map:

code

## Content Map

### Function: parse()
**Primary source:** src/parser.rs:45-60
**Related sources found:**
- tests/parser_test.rs:100-150 (usage examples, edge cases)
- src/types.rs:10-25 (Token type definition)
- docs/design.md:30-45 (recursive descent explanation)
- examples/basic_usage.rs:20-35 (real-world example)

**Coverage:** ✅ Complete (signature, behavior, examples, design rationale)

### Type: Token
**Primary source:** src/types.rs:10-25
**Related sources found:**
- src/lexer.rs:80-120 (Token creation)
- tests/token_test.rs:50-80 (all variants tested)

**Coverage:** ✅ Complete (definition, creation, usage)

### Concept: Error Recovery
**Primary source:** src/parser.rs:300-350
**Related sources found:**
- (none found in tests/)
- (no design docs found)

**Coverage:** ⚠️ Partial (implementation exists, no design rationale or examples)

Example Workflow:

code

User provides: src/parser.rs

Claude discovers:
1. Functions: parse(), tokenize(), validate()
2. For parse():
   → Search tests/ for "parse" → Found tests/parser_test.rs
   → Check imports in test file → Found src/types.rs (Token definition)
   → Search docs/ for "parse" → Found docs/design.md
   → Check examples/ → Found examples/basic_usage.rs
3. For Token type:
   → Search for "Token" in codebase → Found src/lexer.rs (creation)
   → Found tests/token_test.rs (all variants)
4. For validate():
   → Search tests/ for "validate" → Found tests/validator_test.rs
   ...

Result: Comprehensive source list discovered automatically

⚠️ Trust all sources - Don't judge quality or note contradictions. If contradictions exist, write-docs will handle them during generation.

Step 5: Save Requirements File

Always save to: docs/doc-requirements.md

File contains:

•Document type and target audience
•All discovered sources (core + related)
•Document structure with sections
•Content map (what to document from where)

File format:

markdown

# Documentation Requirements

**Created**: 2025-10-22
**Document Type**: API Reference
**Target Audience**: Developers integrating the parser

## Discovered Sources

### Core Sources (user-provided):
- src/parser.rs

### Related Sources (discovered):
- tests/parser_test.rs (usage examples)
- src/types.rs (type definitions)
- docs/design.md (design rationale)
- examples/basic_usage.rs (real-world usage)
- src/lexer.rs (related functionality)
- tests/token_test.rs (type examples)

Total: 7 sources

## Document Structure

- [ ] Introduction
- [ ] Core Concepts
- [ ] Functions (parse, tokenize, validate)
- [ ] Types (Token, AST, ParseError)
- [ ] Usage Patterns
- [ ] Limitations

## Content Map

### Function: parse()
**Primary source:** src/parser.rs:45-60
**Related sources:**
- tests/parser_test.rs:100-150 (usage examples)
- src/types.rs:10-25 (Token type)
- docs/design.md:30-45 (design rationale)

### Type: Token
**Primary source:** src/types.rs:10-25
**Related sources:**
- src/lexer.rs:80-120 (construction)
- tests/token_test.rs:50-80 (examples)

After saving, confirm to user:

"문서 요구사항을 docs/doc-requirements.md에 저장했습니다. 'write-docs 실행해줘'를 입력하면 자동으로 문서를 생성합니다."

Tips for Effective Preparation

•Ask before assuming - If user's intent is unclear during initial setup, ask clarifying questions
•Suggest recommendations - "parser 모듈이니까 API Reference가 적합해 보입니다"
•Document discovery thoroughly - Build comprehensive content map showing all discovered sources for each documentable item

Conclusion

After completing this preparation workflow, you should have:

✅ All sources discovered (core + related) ✅ Document type and structure defined ✅ Content map showing what to document from where ✅ Requirements file saved to docs/doc-requirements.md