Initial commit
This commit is contained in:
Zhongwei Li
90
skills/knowledge-capture/SKILL.md
Normal file
90
skills/knowledge-capture/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: knowledge-capture
|
||||
description: Transform conversations and discussions into structured Notion documentation
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Knowledge Capture skill transforms conversations, discussions, and unstructured information into organized, structured documentation in Notion. It helps you preserve institutional knowledge by capturing important conversations and converting them into actionable, well-formatted documentation.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when you need to:
|
||||
- Convert transcripts or conversation notes into structured documentation
|
||||
- Create meeting summaries with action items
|
||||
- Build knowledge base articles from discussions
|
||||
- Archive important conversations for future reference
|
||||
- Extract key insights and decisions from discussions
|
||||
|
||||
## Features
|
||||
|
||||
- **Smart Content Extraction**: Automatically identifies key points, decisions, and action items from conversations
|
||||
- **Structured Organization**: Creates well-organized Notion documents with proper hierarchy
|
||||
- **Metadata Capture**: Preserves participants, dates, and context information
|
||||
- **Action Item Tracking**: Extracts and formats action items with ownership and deadlines
|
||||
- **Cross-linking**: Automatically creates links to related documentation and team members
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Notion API Access**: Integration token with appropriate permissions
|
||||
- **Target Workspace**: Notion workspace where documentation will be stored
|
||||
- **Template (Optional)**: Pre-defined Notion template for consistent structure
|
||||
|
||||
## Implementation Details
|
||||
|
||||
This skill uses the Notion API to:
|
||||
|
||||
1. Parse input content (text, transcripts, or discussion notes)
|
||||
2. Extract key information using structural analysis
|
||||
3. Format content according to Notion document standards
|
||||
4. Create or update Notion pages with captured knowledge
|
||||
5. Maintain cross-references and relationships
|
||||
|
||||
### Typical Workflow
|
||||
|
||||
```
|
||||
Input: Conversation/Discussion
|
||||
↓
|
||||
Parse & Extract
|
||||
↓
|
||||
Identify: Key Points, Decisions, Action Items
|
||||
↓
|
||||
Format for Notion
|
||||
↓
|
||||
Create/Update Notion Document
|
||||
↓
|
||||
Output: Structured Documentation
|
||||
```
|
||||
|
||||
## Example Use Cases
|
||||
|
||||
1. **Team Meeting Notes**
|
||||
- Input: Meeting transcript
|
||||
- Output: Organized meeting summary with decisions and next steps
|
||||
|
||||
2. **Customer Call Documentation**
|
||||
- Input: Call notes and transcript
|
||||
- Output: Customer interaction record with key requirements
|
||||
|
||||
3. **Architecture Discussion**
|
||||
- Input: Design discussion notes
|
||||
- Output: Architectural decision record with alternatives and rationale
|
||||
|
||||
4. **Interview Notes**
|
||||
- Input: Interview transcript
|
||||
- Output: Structured candidate or user research documentation
|
||||
|
||||
## Configuration
|
||||
|
||||
Set up these environment variables or Notion settings:
|
||||
|
||||
```env
|
||||
NOTION_API_TOKEN=your_token_here
|
||||
NOTION_DATABASE_ID=your_database_id
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Research Documentation](/skills/research-documentation) - For research-focused documentation
|
||||
- [Meeting Intelligence](/skills/meeting-intelligence) - For meeting preparation and follow-up
|
||||
- [Notion API Documentation](https://developers.notion.com)
|
||||
142
skills/knowledge-capture/evaluations/README.md
Normal file
142
skills/knowledge-capture/evaluations/README.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Knowledge Capture - Evaluation Scenarios
|
||||
|
||||
This directory contains test scenarios for validating the Knowledge Capture skill across different Claude models.
|
||||
|
||||
## Overview
|
||||
|
||||
These evaluations ensure that Knowledge Capture works consistently and effectively with:
|
||||
- Claude 3 Haiku
|
||||
- Claude 3 Sonnet
|
||||
- Claude 3 Opus
|
||||
|
||||
Each scenario includes:
|
||||
- **Input**: The conversation or content to capture
|
||||
- **Expected Behavior**: What the skill should do
|
||||
- **Success Criteria**: How to verify success
|
||||
|
||||
## Running Evaluations
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. Copy the conversation/input from a scenario
|
||||
2. Activate Knowledge Capture skill in Claude Code
|
||||
3. Request to capture it as specified
|
||||
4. Evaluate against the success criteria
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- Basic conversation capture
|
||||
- Different documentation types
|
||||
- Complex multi-topic discussions
|
||||
- Action item extraction
|
||||
- Decision documentation
|
||||
- Error handling
|
||||
|
||||
## Scenarios
|
||||
|
||||
### scenario-1-meeting-notes.json
|
||||
**Type**: Meeting Summary Capture
|
||||
**Complexity**: Medium
|
||||
**Input**: Unstructured meeting notes from a team discussion
|
||||
**Expected Output**: Structured meeting summary with decisions and action items
|
||||
**Success Criteria**: All action items identified, decisions documented, participants listed
|
||||
|
||||
### scenario-2-architecture-discussion.json
|
||||
**Type**: Decision Record Capture
|
||||
**Complexity**: Medium-High
|
||||
**Input**: Complex technical architecture discussion
|
||||
**Expected Output**: Decision record with options considered and rationale
|
||||
**Success Criteria**: All alternatives documented, clear decision stated, consequences identified
|
||||
|
||||
### scenario-3-quick-context.json
|
||||
**Type**: Quick Capture
|
||||
**Complexity**: Low
|
||||
**Input**: Brief status update
|
||||
**Expected Output**: Quick reference document
|
||||
**Success Criteria**: Key points captured, properly formatted
|
||||
|
||||
### scenario-4-action-items-focus.json
|
||||
**Type**: Action Item Extraction
|
||||
**Complexity**: Medium
|
||||
**Input**: Meeting with many scattered action items
|
||||
**Expected Output**: Clear list of who, what, when
|
||||
**Success Criteria**: All action items found, owners assigned, deadlines noted
|
||||
|
||||
### scenario-5-learning-from-incident.json
|
||||
**Type**: Learning Document
|
||||
**Complexity**: High
|
||||
**Input**: Post-incident discussion about what went wrong
|
||||
**Expected Output**: Learning document with best practices
|
||||
**Success Criteria**: Root causes identified, lessons extracted, preventive measures noted
|
||||
|
||||
## Evaluation Criteria
|
||||
|
||||
### Comprehensiveness
|
||||
- Did the skill capture all key information?
|
||||
- Were important details missed?
|
||||
- Is the output complete?
|
||||
|
||||
### Structure
|
||||
- Is the output well-organized?
|
||||
- Are headings and sections appropriate?
|
||||
- Does it follow the documentation type's structure?
|
||||
|
||||
### Actionability
|
||||
- Are action items clear and assignable?
|
||||
- Are next steps defined?
|
||||
- Can someone understand what to do next?
|
||||
|
||||
### Linking
|
||||
- Are cross-references included?
|
||||
- Could this be discovered from related docs?
|
||||
- Are important connections made?
|
||||
|
||||
### Accuracy
|
||||
- Is the captured information accurate?
|
||||
- Were details misinterpreted?
|
||||
- Does it faithfully represent the source?
|
||||
|
||||
## Model-Specific Notes
|
||||
|
||||
### Haiku
|
||||
- May need slightly more structured input
|
||||
- Evaluates on accuracy and completeness
|
||||
- Good for quick captures
|
||||
|
||||
### Sonnet
|
||||
- Handles complex discussions well
|
||||
- Good at inferring structure
|
||||
- Balanced performance across all scenario types
|
||||
|
||||
### Opus
|
||||
- Excels at inferring structure from unstructured input
|
||||
- Best for complex, multi-topic discussions
|
||||
- Highest accuracy on nuanced extraction
|
||||
|
||||
## Failure Modes to Watch For
|
||||
|
||||
1. **Orphaning**: Documentation created without linking to hub pages
|
||||
2. **Structure Loss**: Loss of hierarchical organization
|
||||
3. **Missing Details**: Key decisions or action items not captured
|
||||
4. **Wrong Type**: Documentation created as wrong type (e.g., FAQ instead of Decision Record)
|
||||
5. **Broken Context**: Missing important contextual information
|
||||
6. **Inaccuracy**: Misinterpretation of what was discussed
|
||||
|
||||
## Updating Scenarios
|
||||
|
||||
When updating scenarios:
|
||||
1. Ensure they reflect real-world use cases
|
||||
2. Include edge cases and challenging inputs
|
||||
3. Keep success criteria clear and measurable
|
||||
4. Test with all three model sizes
|
||||
5. Document any model-specific behavior
|
||||
|
||||
## Expected Performance
|
||||
|
||||
**Target Success Rate**: 90%+ on Sonnet and Opus, 85%+ on Haiku
|
||||
|
||||
When a scenario fails:
|
||||
1. Review the specific failure mode
|
||||
2. Check if it's a consistent issue or model-specific
|
||||
3. Update the skill prompt if needed
|
||||
4. Document the failure and resolution
|
||||
@@ -0,0 +1,99 @@
|
||||
{
|
||||
"id": "scenario-1-meeting-notes",
|
||||
"name": "Meeting Notes Capture",
|
||||
"description": "Convert unstructured meeting notes into a structured meeting summary",
|
||||
"complexity": "medium",
|
||||
"input_type": "meeting_notes",
|
||||
"output_type": "meeting_summary",
|
||||
"input": {
|
||||
"context": "Team planning meeting about Q4 roadmap",
|
||||
"content": "Had a meeting today with product, engineering, and design about Q4 priorities. We talked about the fact that customers have been asking for dark mode for a while - it's our most requested feature. Sarah (PM) said we should prioritize it, and Mike (design) showed mockups that look great. The engineering team (me, Alex, and Jordan) think we can get it done in 2 sprints if we focus. We also talked about the mobile app - James mentioned that iOS performance is slow when rendering large lists. We didn't decide on a timeline for that yet. Alex volunteered to look into virtualization. For dark mode, we decided to ship it with a toggle in settings that persists to the database. Next steps: Sarah will write the spec this week, Mike will finalize designs by end of week, and our team will start on implementation next sprint. We also have some tech debt from the old auth system that Mike thinks is slowing us down, but we deferred that to next quarter. Finally, we need a QA plan for dark mode - Jessica said she'd put together a testing plan."
|
||||
},
|
||||
"expected_output": {
|
||||
"document_type": "meeting_summary",
|
||||
"structure": {
|
||||
"title": "Q4 Roadmap Planning - Team Meeting",
|
||||
"sections": [
|
||||
"Meeting Details",
|
||||
"Key Decisions",
|
||||
"Action Items",
|
||||
"Topics Discussed",
|
||||
"Deferred Items"
|
||||
]
|
||||
},
|
||||
"key_decisions": [
|
||||
{
|
||||
"decision": "Prioritize dark mode implementation",
|
||||
"rationale": "Most frequently requested customer feature"
|
||||
},
|
||||
{
|
||||
"decision": "Dark mode will use toggle in settings with database persistence",
|
||||
"rationale": "User preference persistence requirement"
|
||||
}
|
||||
],
|
||||
"action_items": [
|
||||
{
|
||||
"owner": "Sarah",
|
||||
"task": "Write dark mode specification",
|
||||
"deadline": "This week"
|
||||
},
|
||||
{
|
||||
"owner": "Mike",
|
||||
"task": "Finalize dark mode design mockups",
|
||||
"deadline": "End of week"
|
||||
},
|
||||
{
|
||||
"owner": "Engineering team",
|
||||
"task": "Begin dark mode implementation",
|
||||
"deadline": "Next sprint"
|
||||
},
|
||||
{
|
||||
"owner": "Alex",
|
||||
"task": "Investigate list virtualization for iOS performance",
|
||||
"deadline": "TBD"
|
||||
},
|
||||
{
|
||||
"owner": "Jessica",
|
||||
"task": "Create QA test plan for dark mode",
|
||||
"deadline": "TBD"
|
||||
}
|
||||
],
|
||||
"attendees": [
|
||||
"Sarah (Product)",
|
||||
"Mike (Design)",
|
||||
"Engineering: self, Alex, Jordan",
|
||||
"James (mentioned iOS issues)",
|
||||
"Jessica (QA)"
|
||||
]
|
||||
},
|
||||
"success_criteria": {
|
||||
"must_capture": [
|
||||
"Meeting purpose and date",
|
||||
"All participants/roles",
|
||||
"Both major decisions with rationale",
|
||||
"All 5 action items with owners and deadlines",
|
||||
"Topics discussed (dark mode, mobile performance, tech debt)",
|
||||
"Implementation timeline (2 sprints for dark mode)"
|
||||
],
|
||||
"should_capture": [
|
||||
"Design mockups mentioned",
|
||||
"Tech debt deferred to Q1",
|
||||
"Connection to customer requests"
|
||||
],
|
||||
"must_not_do": [
|
||||
"Invent action items not mentioned",
|
||||
"Misassign ownership",
|
||||
"Lose deadline information",
|
||||
"Create orphaned document without linking context"
|
||||
]
|
||||
},
|
||||
"evaluation_notes": {
|
||||
"difficulty": "Medium - requires extracting structure from unstructured narrative",
|
||||
"key_challenge": "Identifying implicit decisions and action items from conversation flow",
|
||||
"model_variations": {
|
||||
"haiku": "May miss some implicit items, but should catch main points",
|
||||
"sonnet": "Should capture all explicit items and most implicit ones",
|
||||
"opus": "Should capture full context with implicit relationships"
|
||||
}
|
||||
}
|
||||
}
|
||||
115
skills/knowledge-capture/examples/example-meeting-summary.md
Normal file
115
skills/knowledge-capture/examples/example-meeting-summary.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Example: Meeting Summary Capture
|
||||
|
||||
## Before (Raw Input)
|
||||
|
||||
```
|
||||
Had a good meeting today with the product and design teams about authentication.
|
||||
We talked about moving to passwordless auth using passkeys. Sarah brought up
|
||||
that we need to support legacy systems, so we can't go all-in yet. Mike showed
|
||||
designs for the new flow - looks great. We decided to do a phased rollout:
|
||||
Phase 1 is passkeys in web, Phase 2 is mobile, Phase 3 is legacy support.
|
||||
Sarah will write the spec, Mike will handle design across all phases, and I'll
|
||||
coordinate engineering. We also talked about the performance issues with the
|
||||
current auth - not a blocker but something we should keep an eye on. The new
|
||||
architecture should fix that anyway. Need to talk to infra about deployment,
|
||||
and we'll need a migration plan for existing users.
|
||||
```
|
||||
|
||||
## After (Captured in Notion)
|
||||
|
||||
### Meeting Summary: Passwordless Authentication Strategy
|
||||
|
||||
**Date:** November 9, 2025
|
||||
**Attendees:** Sarah (Product), Mike (Design), Engineering Lead
|
||||
**Duration:** 1 hour
|
||||
**Status:** Decisions Made
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Decision 1: Implement Passwordless Authentication via Passkeys
|
||||
- **Decision:** Migrate to passkey-based authentication
|
||||
- **Rationale:** Improved security and user experience
|
||||
- **Phase Approach:** Phased rollout required due to legacy system constraints
|
||||
|
||||
### Decision 2: Phased Rollout Strategy
|
||||
- **Phase 1:** Passkeys in web applications
|
||||
- **Phase 2:** Mobile app support
|
||||
- **Phase 3:** Legacy system support and migration
|
||||
- **Rationale:** Allows gradual adoption while maintaining backward compatibility
|
||||
|
||||
---
|
||||
|
||||
## Action Items
|
||||
|
||||
| Owner | Task | Deadline | Status |
|
||||
|-------|------|----------|--------|
|
||||
| Sarah (Product) | Write passwordless auth specification with phase requirements | This week | Not Started |
|
||||
| Mike (Design) | Create design mockups for all authentication flows across phases | End of week | In Progress |
|
||||
| Engineering Lead | Coordinate engineering effort and infrastructure planning | Next sprint | Not Started |
|
||||
| Infrastructure | Plan deployment strategy and production rollout approach | TBD | Not Started |
|
||||
|
||||
---
|
||||
|
||||
## Discussion Topics
|
||||
|
||||
### Passwordless Authentication
|
||||
- Passkeys provide strong security posture
|
||||
- User experience benefits over traditional passwords
|
||||
- Industry standard approach (WebAuthn/FIDO2)
|
||||
|
||||
### Legacy System Constraints
|
||||
- Cannot immediately deprecate password authentication
|
||||
- Existing systems require continued support
|
||||
- Migration path needed for users on legacy platforms
|
||||
|
||||
### Performance Considerations
|
||||
- Current auth system has performance overhead
|
||||
- New architecture should resolve existing performance issues
|
||||
- Not a blocker for implementation but important improvement
|
||||
|
||||
### Migration Planning
|
||||
- Need clear plan for existing user migration
|
||||
- Gradual rollout reduces risk
|
||||
- Each phase builds on previous phase
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **This Week:** Sarah delivers detailed specification
|
||||
2. **End of Week:** Design mockups finalized for review
|
||||
3. **Next Sprint:** Engineering begins Phase 1 (web) implementation
|
||||
4. **Parallel:** Infrastructure team plans deployment and migration strategy
|
||||
5. **TBD:** User communication plan for authentication transition
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Authentication Architecture Decision Record](notion://decision-record-url)
|
||||
- [Security Requirements Specification](notion://spec-url)
|
||||
- [Q4 Product Roadmap](notion://roadmap-url)
|
||||
- [Infrastructure Planning](notion://infra-url)
|
||||
|
||||
## Tags
|
||||
|
||||
`authentication` `security` `product-initiative` `phased-rollout` `decision-record`
|
||||
|
||||
## Follow-up Items
|
||||
|
||||
- [ ] Schedule follow-up meeting after specs are written
|
||||
- [ ] Plan QA testing strategy for each phase
|
||||
- [ ] Create user communication plan
|
||||
- [ ] Schedule infrastructure review of deployment plan
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Performance improvement** is a nice-to-have benefit of new architecture
|
||||
- **Backward compatibility** is critical for adoption success
|
||||
- **Phasing** reduces implementation risk and allows for feedback cycles
|
||||
|
||||
**Owner:** Sarah (Product) | **Last Updated:** November 9, 2025 | **Next Review:** November 23, 2025
|
||||
161
skills/knowledge-capture/reference/best-practices.md
Normal file
161
skills/knowledge-capture/reference/best-practices.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Knowledge Capture - Best Practices
|
||||
|
||||
Guidelines for capturing knowledge effectively in Notion.
|
||||
|
||||
## Timing
|
||||
|
||||
**Capture Promptly**
|
||||
- Document while context is fresh
|
||||
- Aim to capture within 24 hours of the conversation
|
||||
- Create placeholder if you'll document later
|
||||
|
||||
**Regular Maintenance**
|
||||
- Review quarterly for accuracy
|
||||
- Update links if pages move
|
||||
- Archive outdated documentation
|
||||
- Mark superseded content clearly
|
||||
|
||||
## Structure & Organization
|
||||
|
||||
**Clear Hierarchy**
|
||||
- Use proper heading levels (H1, H2, H3, etc.)
|
||||
- One main idea per section
|
||||
- Logical flow from overview to details
|
||||
- Include table of contents for long documents
|
||||
|
||||
**Consistent Templates**
|
||||
- Use the same structure within document types
|
||||
- Keep headers and sections predictable
|
||||
- Use consistent formatting and styles
|
||||
|
||||
## Content Quality
|
||||
|
||||
**Be Specific**
|
||||
- Use concrete examples over vague descriptions
|
||||
- Include actual code, commands, or workflows
|
||||
- Name specific tools and versions
|
||||
- Be clear about what's required vs. optional
|
||||
|
||||
**Make It Actionable**
|
||||
- Include clear next steps
|
||||
- Provide decision criteria if applicable
|
||||
- List prerequisites upfront
|
||||
- Specify who needs to do what
|
||||
|
||||
**Prevent Orphaning**
|
||||
- Link to hub pages or indexes
|
||||
- Add to relevant category pages
|
||||
- Use tags for discovery
|
||||
- Include "Related Documents" section
|
||||
|
||||
## Linking & Discoverability
|
||||
|
||||
**Strategic Linking**
|
||||
```
|
||||
Example: How-To Guide on "Setting Up CI/CD"
|
||||
|
||||
Links to add:
|
||||
- Source document (e.g., architecture decision)
|
||||
- Related documents (deployment guide, monitoring)
|
||||
- Hub page (DevOps/Infrastructure index)
|
||||
- Team/person pages (who uses this)
|
||||
```
|
||||
|
||||
**Tagging Strategy**
|
||||
- Use consistent tag names across org
|
||||
- Don't over-tag (3-5 tags per document)
|
||||
- Use hierarchical tags: `process/deployment`, `tool/github`
|
||||
- Example tags: `how-to`, `urgent`, `team-core`, `deprecated`
|
||||
|
||||
**Searchable Content**
|
||||
- Use descriptive titles (not "Meeting Notes", use "Q4 Planning - Nov 9")
|
||||
- Include keywords in description
|
||||
- Put important terms in headings
|
||||
- Use consistent terminology
|
||||
|
||||
## Collaborative Documentation
|
||||
|
||||
**Ownership & Updates**
|
||||
- Designate an owner for each document
|
||||
- Include last-updated date
|
||||
- Make update process clear (who can edit)
|
||||
- Document version/change history if needed
|
||||
|
||||
**Review Cycle**
|
||||
- Schedule reviews for time-sensitive docs (quarterly for most)
|
||||
- Mark review dates in document
|
||||
- Create task reminders for reviews
|
||||
- Document what changed and why
|
||||
|
||||
**Avoiding Duplication**
|
||||
- Search before creating new docs
|
||||
- Link to existing docs instead of copying
|
||||
- Mark outdated docs clearly
|
||||
- Consolidate when possible
|
||||
|
||||
## Different Formats
|
||||
|
||||
**Short Documents (< 5 screens)**
|
||||
- Single Notion page
|
||||
- No special structure needed
|
||||
- Still add tags and links
|
||||
|
||||
**Medium Documents (5-20 screens)**
|
||||
- Use databases for modular content
|
||||
- Create table of contents
|
||||
- Add navigation between sections
|
||||
|
||||
**Long Documents (> 20 screens)**
|
||||
- Consider breaking into multiple pages
|
||||
- Create parent pages with sub-pages
|
||||
- Add clear navigation
|
||||
- Link to each section from TOC
|
||||
|
||||
## Maintenance Patterns
|
||||
|
||||
**Quarterly Review Checklist**
|
||||
- [ ] Is this still accurate?
|
||||
- [ ] Are links still valid?
|
||||
- [ ] Should we archive or consolidate?
|
||||
- [ ] Are examples still relevant?
|
||||
- [ ] Do we need to update tools/versions?
|
||||
|
||||
**Update Notification**
|
||||
- When updating significant docs: notify stakeholders
|
||||
- Add summary of what changed
|
||||
- Update linked documents if needed
|
||||
- Note the update in a changelog if important
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
1. **Orphaned Documentation**: Always link to hub pages
|
||||
2. **Outdated Examples**: Date-stamp time-sensitive information
|
||||
3. **Vague Instructions**: Include specific steps and expected output
|
||||
4. **No Context**: Explain why this documentation exists
|
||||
5. **Over-Linking**: 3-5 key links is usually enough
|
||||
6. **Inconsistent Format**: Follow templates for similar doc types
|
||||
7. **Missing Ownership**: Know who maintains what
|
||||
8. **Broken Links**: Periodically check and fix internal links
|
||||
|
||||
## Examples of Great Documentation
|
||||
|
||||
Look for these characteristics in well-documented knowledge:
|
||||
|
||||
✓ Clear purpose stated upfront
|
||||
✓ Specific examples and code
|
||||
✓ Step-by-step instructions when applicable
|
||||
✓ Links to prerequisites and related docs
|
||||
✓ Date or version information
|
||||
✓ Clear ownership/maintainer
|
||||
✓ Table of contents for long docs
|
||||
✓ Searchable keywords in title and headings
|
||||
|
||||
## Tools & Templates
|
||||
|
||||
See the `templates/` directory for:
|
||||
- How-To template
|
||||
- Decision Record template
|
||||
- FAQ template
|
||||
- Meeting Summary template
|
||||
- Learning Document template
|
||||
- Process Documentation template
|
||||
213
skills/knowledge-capture/reference/documentation-types.md
Normal file
213
skills/knowledge-capture/reference/documentation-types.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Knowledge Capture - Documentation Types Guide
|
||||
|
||||
This guide explains the different documentation types that Knowledge Capture can create and when to use each one.
|
||||
|
||||
## Documentation Types
|
||||
|
||||
### 1. How-To Guides
|
||||
|
||||
**Purpose:** Step-by-step instructions for accomplishing a specific task
|
||||
|
||||
**Structure:**
|
||||
- Title (action-oriented, e.g., "How to Set Up OAuth")
|
||||
- Overview (what this guide covers and why it matters)
|
||||
- Prerequisites (knowledge, tools, or access needed)
|
||||
- Numbered Steps (clear, sequential instructions)
|
||||
- Troubleshooting (common issues and solutions)
|
||||
- Related Resources (links to other documentation)
|
||||
|
||||
**Example Context:**
|
||||
```
|
||||
Conversation about: Implementing authentication flow
|
||||
→ Knowledge Capture suggests: How-To Guide
|
||||
→ Output: "How to Implement OAuth 2.0 in Node.js"
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Keep steps atomic (one action per step)
|
||||
- Include expected outputs/confirmations
|
||||
- Add screenshots or examples when possible
|
||||
- Test instructions before publishing
|
||||
|
||||
---
|
||||
|
||||
### 2. Decision Records
|
||||
|
||||
**Purpose:** Document important decisions and their rationale
|
||||
|
||||
**Structure:**
|
||||
- Title (clear decision statement)
|
||||
- Date & Context (when and why this decision was needed)
|
||||
- Problem Statement (what needed to be decided)
|
||||
- Options Considered (alternatives with pros/cons)
|
||||
- Decision (what was decided and why)
|
||||
- Consequences (impacts and follow-ups)
|
||||
- Related Decisions (decisions that connect to this one)
|
||||
|
||||
**Example Context:**
|
||||
```
|
||||
Conversation about: Choosing between microservices and monolith
|
||||
→ Knowledge Capture suggests: Decision Record
|
||||
→ Output: "Architecture Decision: Monolithic vs. Microservices"
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Make decisions explicit and documented
|
||||
- Include options you rejected and why
|
||||
- Document impacts as they become clear
|
||||
- Revisit periodically to validate decisions
|
||||
|
||||
---
|
||||
|
||||
### 3. FAQ Documents
|
||||
|
||||
**Purpose:** Provide quick answers to commonly asked questions
|
||||
|
||||
**Structure:**
|
||||
- Topic Title (the subject area)
|
||||
- Questions (organized by category or importance)
|
||||
- Answers (clear, concise, with examples)
|
||||
- See Also (links to related topics)
|
||||
|
||||
**Example Context:**
|
||||
```
|
||||
Conversation about: Common questions about API usage
|
||||
→ Knowledge Capture suggests: FAQ
|
||||
→ Output: "API Integration FAQ"
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Order by frequency and importance
|
||||
- Keep answers concise but complete
|
||||
- Include code examples where relevant
|
||||
- Link to detailed documentation for deep dives
|
||||
|
||||
---
|
||||
|
||||
### 4. Meeting Summaries
|
||||
|
||||
**Purpose:** Capture outcomes from meetings
|
||||
|
||||
**Structure:**
|
||||
- Meeting Details (date, attendees, purpose)
|
||||
- Key Decisions (what was decided)
|
||||
- Action Items (who, what, when)
|
||||
- Discussion Summary (what was discussed)
|
||||
- Next Steps (what happens next)
|
||||
- Related Materials (linked documents)
|
||||
|
||||
**Example Context:**
|
||||
```
|
||||
Conversation from: Product planning meeting
|
||||
→ Knowledge Capture suggests: Meeting Summary
|
||||
→ Output: "Q4 Planning Meeting - November 9, 2025"
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Capture decisions and action items immediately
|
||||
- Make action items specific and assignable
|
||||
- Link to relevant documentation
|
||||
- Distribute summary within 24 hours
|
||||
|
||||
---
|
||||
|
||||
### 5. Learning Documents
|
||||
|
||||
**Purpose:** Preserve knowledge and learning from experiences
|
||||
|
||||
**Structure:**
|
||||
- Situation (context and background)
|
||||
- What Happened (the story or event)
|
||||
- Key Learnings (takeaways and insights)
|
||||
- Best Practices (applicable lessons)
|
||||
- Resources (further reading)
|
||||
- Related Learning (connected documents)
|
||||
|
||||
**Example Context:**
|
||||
```
|
||||
Conversation about: Why a deployment went wrong
|
||||
→ Knowledge Capture suggests: Learning Document
|
||||
→ Output: "Lessons from November Production Incident"
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Focus on patterns and principles
|
||||
- Be honest about mistakes
|
||||
- Emphasize what you'd do differently
|
||||
- Make it practical and actionable
|
||||
|
||||
---
|
||||
|
||||
### 6. Process Documentation
|
||||
|
||||
**Purpose:** Document standard processes and workflows
|
||||
|
||||
**Structure:**
|
||||
- Process Name (clear, action-oriented)
|
||||
- Purpose (why this process exists)
|
||||
- Scope (when and where it applies)
|
||||
- Responsibilities (who does what)
|
||||
- Steps (detailed workflow)
|
||||
- Approval (if needed)
|
||||
- Review Schedule (how often to revisit)
|
||||
|
||||
**Example Context:**
|
||||
```
|
||||
Conversation about: How code reviews work in the team
|
||||
→ Knowledge Capture suggests: Process Documentation
|
||||
→ Output: "Code Review Process"
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Keep current with team changes
|
||||
- Include decision points and escalation paths
|
||||
- Make roles and responsibilities clear
|
||||
- Version and date your processes
|
||||
|
||||
---
|
||||
|
||||
## Selection Guidance
|
||||
|
||||
Use this flowchart to determine the best documentation type:
|
||||
|
||||
```
|
||||
Question: What are you capturing?
|
||||
|
||||
├─ A task someone needs to do?
|
||||
│ └─ How-To Guide
|
||||
│
|
||||
├─ A decision that was made?
|
||||
│ └─ Decision Record
|
||||
│
|
||||
├─ Repeated questions?
|
||||
│ └─ FAQ
|
||||
│
|
||||
├─ What happened in a meeting?
|
||||
│ └─ Meeting Summary
|
||||
│
|
||||
├─ An experience to learn from?
|
||||
│ └─ Learning Document
|
||||
│
|
||||
└─ A repeated workflow?
|
||||
└─ Process Documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Linking Documentation
|
||||
|
||||
Once created, ensure new documentation is discoverable:
|
||||
|
||||
1. **Hub Pages**: Add to relevant index or category pages
|
||||
2. **Backlinks**: Link from source materials
|
||||
3. **Tags**: Use consistent tagging for search
|
||||
4. **Cross-references**: Link to related documentation
|
||||
|
||||
## Best Practices Across All Types
|
||||
|
||||
- **Consistent Format**: Follow the structure for your doc type
|
||||
- **Clear Titles**: Use descriptive, searchable titles
|
||||
- **Dated/Versioned**: Include dates, especially for time-sensitive info
|
||||
- **Author/Owner**: Know who to ask about updates
|
||||
- **Regular Review**: Schedule periodic reviews to keep current
|
||||
- **Examples**: Include concrete examples and templates
|
||||
Reference in New Issue
Block a user