162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# 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
|