Initial commit

skills/knowledge-capture/reference/best-practices.md

@@ -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