zhongwei/gh-tommy-ca-notion-skills-plugins-notion-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:02:23 +08:00
commit 5f44d04a64
18 changed files with 1976 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
skills/knowledge-capture/reference/best-practices.md Normal file
View 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
View 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