Initial commit: Claude Skills Factory with 8 refined custom skills
Custom Skills (ourdigital-custom-skills/): - 00-ourdigital-visual-storytelling: Blog featured image prompt generator - 01-ourdigital-research-publisher: Research-to-publication workflow - 02-notion-organizer: Notion workspace management - 03-research-to-presentation: Notion research to PPT/Figma - 04-seo-gateway-strategist: SEO gateway page strategy planning - 05-gateway-page-content-builder: Gateway page content generation - 20-jamie-brand-editor: Jamie Clinic branded content GENERATION - 21-jamie-brand-guardian: Jamie Clinic content REVIEW & evaluation Refinements applied: - All skills converted to SKILL.md format with YAML frontmatter - Added version fields to all skills - Flattened nested folder structures - Removed packaging artifacts (.zip, .skill files) - Reorganized file structures (scripts/, references/, etc.) - Differentiated Jamie skills with clear roles 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
203
official-skils-collection/notion-knowledge-capture/SKILL.md
Normal file
203
official-skils-collection/notion-knowledge-capture/SKILL.md
Normal file
@@ -0,0 +1,203 @@
|
||||
---
|
||||
name: notion-knowledge-capture
|
||||
description: Transforms conversations and discussions into structured documentation pages in Notion. Captures insights, decisions, and knowledge from chat context, formats appropriately, and saves to wikis or databases with proper organization and linking for easy discovery.
|
||||
---
|
||||
|
||||
# Knowledge Capture
|
||||
|
||||
Transforms conversations, discussions, and insights into structured documentation in your Notion workspace. Captures knowledge from chat context, formats it appropriately, and saves it to the right location with proper organization and linking.
|
||||
|
||||
## Quick Start
|
||||
|
||||
When asked to save information to Notion:
|
||||
|
||||
1. **Extract content**: Identify key information from conversation context
|
||||
2. **Structure information**: Organize into appropriate documentation format
|
||||
3. **Determine location**: Use `Notion:notion-search` to find appropriate wiki page/database
|
||||
4. **Create page**: Use `Notion:notion-create-pages` to save content
|
||||
5. **Make discoverable**: Link from relevant hub pages, add to databases, or update wiki navigation so others can find it
|
||||
|
||||
## Knowledge Capture Workflow
|
||||
|
||||
### Step 1: Identify content to capture
|
||||
|
||||
```
|
||||
From conversation context, extract:
|
||||
- Key concepts and definitions
|
||||
- Decisions made and rationale
|
||||
- How-to information and procedures
|
||||
- Important insights or learnings
|
||||
- Q&A pairs
|
||||
- Examples and use cases
|
||||
```
|
||||
|
||||
### Step 2: Determine content type
|
||||
|
||||
```
|
||||
Classify the knowledge:
|
||||
- Concept/Definition
|
||||
- How-to Guide
|
||||
- Decision Record
|
||||
- FAQ Entry
|
||||
- Meeting Summary
|
||||
- Learning/Post-mortem
|
||||
- Reference Documentation
|
||||
```
|
||||
|
||||
|
||||
### Step 3: Structure the content
|
||||
|
||||
```
|
||||
Format appropriately based on content type:
|
||||
- Use templates for consistency
|
||||
- Add clear headings and sections
|
||||
- Include examples where helpful
|
||||
- Add relevant metadata
|
||||
- Link to related pages
|
||||
```
|
||||
|
||||
|
||||
### Step 4: Determine destination
|
||||
|
||||
```
|
||||
Where to save:
|
||||
- Wiki page (general knowledge base)
|
||||
- Specific project page (project-specific knowledge)
|
||||
- Documentation database (structured docs)
|
||||
- FAQ database (questions and answers)
|
||||
- Decision log (architecture/product decisions)
|
||||
- Team wiki (team-specific knowledge)
|
||||
```
|
||||
|
||||
### Step 5: Create the page
|
||||
|
||||
```
|
||||
Use Notion:notion-create-pages:
|
||||
- Set appropriate title
|
||||
- Use structured content from template
|
||||
- Set properties if in database
|
||||
- Add tags/categories
|
||||
- Link to related pages
|
||||
```
|
||||
|
||||
### Step 6: Make content discoverable
|
||||
|
||||
```
|
||||
Link the new page so others can find it:
|
||||
|
||||
1. Update hub/index pages:
|
||||
- Add link to wiki table of contents page
|
||||
- Add link from relevant project page
|
||||
- Add link from category/topic page (e.g., "Engineering Docs")
|
||||
|
||||
2. If page is in a database:
|
||||
- Set appropriate tags/categories
|
||||
- Set status (e.g., "Published")
|
||||
- Add to relevant views
|
||||
|
||||
3. Optionally update parent page:
|
||||
- If saved under a project, add to project's "Documentation" section
|
||||
- If in team wiki, ensure it's linked from team homepage
|
||||
|
||||
Example:
|
||||
Notion:notion-update-page
|
||||
page_id: "team-wiki-homepage-id"
|
||||
command: "insert_content_after"
|
||||
selection_with_ellipsis: "## How-To Guides..."
|
||||
new_str: "- <mention-page url='...'>How to Deploy to Production</mention-page>"
|
||||
```
|
||||
|
||||
This step ensures the knowledge doesn't become "orphaned" - it's properly connected to your workspace's navigation structure.
|
||||
|
||||
## Content Types
|
||||
|
||||
Choose appropriate structure based on content:
|
||||
|
||||
**Concept**: Overview → Definition → Characteristics → Examples → Use Cases → Related
|
||||
**How-To**: Overview → Prerequisites → Steps (numbered) → Verification → Troubleshooting → Related
|
||||
**Decision**: Context → Decision → Rationale → Options Considered → Consequences → Implementation
|
||||
**FAQ**: Short Answer → Detailed Explanation → Examples → When to Use → Related Questions
|
||||
**Learning**: What Happened → What Went Well → What Didn't → Root Causes → Learnings → Actions
|
||||
|
||||
|
||||
## Destination Patterns
|
||||
|
||||
**General Wiki**: Standalone page → add to index → tag → link from related pages
|
||||
|
||||
**Project Wiki**: Child of project page → link from project overview → tag with project name
|
||||
|
||||
**Documentation Database**: Use properties (Title, Type, Category, Tags, Last Updated, Owner)
|
||||
|
||||
**Decision Log Database**: Use properties (Decision, Date, Status, Domain, Deciders, Impact)
|
||||
|
||||
**FAQ Database**: Use properties (Question, Category, Tags, Last Reviewed, Useful Count)
|
||||
|
||||
See [reference/database-best-practices.md](reference/database-best-practices.md) for database selection guide and individual schema files.
|
||||
|
||||
## Content Extraction from Conversations
|
||||
|
||||
**Chat Discussion**: Key points, conclusions, resources, action items, Q&A
|
||||
|
||||
**Problem-Solving**: Problem statement, approaches tried, solution, why it worked, future considerations
|
||||
|
||||
**Knowledge Sharing**: Concept explained, examples, best practices, common pitfalls, resources
|
||||
|
||||
**Decision Discussion**: Question, options, trade-offs, decision, rationale, next steps
|
||||
|
||||
## Formatting Best Practices
|
||||
|
||||
**Structure**: Use `#` (title), `##` (sections), `###` (subsections) consistently
|
||||
|
||||
**Writing**: Start with overview, use bullets, keep paragraphs short, add examples
|
||||
|
||||
**Linking**: Link related pages, mention people, reference resources, create bidirectional links
|
||||
|
||||
**Metadata**: Include date, author, tags, status
|
||||
|
||||
**Searchability**: Clear titles, natural keywords, common search tags, image alt-text
|
||||
|
||||
## Indexing and Organization
|
||||
|
||||
**Wiki Index**: Organize by sections (Getting Started, How-To Guides, Reference, FAQs, Decisions) with page links
|
||||
|
||||
**Category Pages**: Create landing pages with overview, doc links, and recent updates
|
||||
|
||||
**Tagging Strategy**: Use consistent tags for technology/tools, topics, audience, and status
|
||||
|
||||
## Update Management
|
||||
|
||||
**Create New**: Content is substantive (>2 paragraphs), will be referenced multiple times, part of knowledge base, needs independent discovery
|
||||
|
||||
**Update Existing**: Adding to existing topic, correcting info, expanding concept, updating for changes
|
||||
|
||||
**Versioning**: Add update history section for significant changes (date, author, what changed, why)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Capture promptly**: Document while context is fresh
|
||||
2. **Structure consistently**: Use templates for similar content
|
||||
3. **Link extensively**: Connect related knowledge
|
||||
4. **Write for discovery**: Use searchable titles and tags
|
||||
5. **Include context**: Why this matters, when to use
|
||||
6. **Add examples**: Concrete examples aid understanding
|
||||
7. **Maintain**: Review and update periodically
|
||||
8. **Get feedback**: Ask if documentation is helpful
|
||||
|
||||
## Advanced Features
|
||||
|
||||
**Documentation databases**: See [reference/database-best-practices.md](reference/database-best-practices.md) for database schema patterns.
|
||||
|
||||
## Common Issues
|
||||
|
||||
**"Not sure where to save"**: Default to general wiki, can move later
|
||||
**"Content is fragmentary"**: Group related fragments into cohesive doc
|
||||
**"Already exists"**: Search first, update existing if appropriate
|
||||
**"Too informal"**: Clean up language while preserving insights
|
||||
|
||||
## Examples
|
||||
|
||||
See [examples/](examples/) for complete workflows:
|
||||
- [examples/conversation-to-faq.md](examples/conversation-to-faq.md) - FAQ from Q&A
|
||||
- [examples/decision-capture.md](examples/decision-capture.md) - Decision record
|
||||
- [examples/how-to-guide.md](examples/how-to-guide.md) - How-to from discussion
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# Knowledge Capture Skill Evaluations
|
||||
|
||||
Evaluation scenarios for testing the Knowledge Capture skill across different Claude models.
|
||||
|
||||
## Purpose
|
||||
|
||||
These evaluations ensure the Knowledge Capture skill:
|
||||
- Correctly identifies content types (how-to guides, FAQs, decision records, wikis)
|
||||
- Extracts relevant information from conversations
|
||||
- Structures content appropriately for each type
|
||||
- Searches and places content in the right Notion location
|
||||
- Works consistently across Haiku, Sonnet, and Opus
|
||||
|
||||
## Evaluation Files
|
||||
|
||||
### conversation-to-wiki.json
|
||||
Tests capturing conversation content as a how-to guide for the team wiki.
|
||||
|
||||
**Scenario**: Save deployment discussion to wiki
|
||||
**Key Behaviors**:
|
||||
- Extracts steps, gotchas, and best practices from conversation
|
||||
- Identifies content as How-To Guide
|
||||
- Structures with proper sections (Overview, Prerequisites, Steps, Troubleshooting)
|
||||
- Searches for team wiki location
|
||||
- Preserves technical details (commands, configs)
|
||||
|
||||
### decision-record.json
|
||||
Tests capturing architectural or technical decisions with full context.
|
||||
|
||||
**Scenario**: Document database migration decision
|
||||
**Key Behaviors**:
|
||||
- Extracts decision context, alternatives, and rationale
|
||||
- Follows decision record structure (Context, Decision, Alternatives, Consequences)
|
||||
- Captures both selected and rejected options with reasoning
|
||||
- Places in decision log or ADR database
|
||||
- Links to related technical documentation
|
||||
|
||||
## Running Evaluations
|
||||
|
||||
1. Enable the `knowledge-capture` skill
|
||||
2. Submit the query from the evaluation file
|
||||
3. Provide conversation context as specified
|
||||
4. Verify all expected behaviors are met
|
||||
5. Check success criteria for quality
|
||||
6. Test with Haiku, Sonnet, and Opus
|
||||
|
||||
## Expected Skill Behaviors
|
||||
|
||||
Knowledge Capture evaluations should verify:
|
||||
|
||||
### Content Extraction
|
||||
- Accurately captures key points from conversation context
|
||||
- Preserves specific technical details, not generic placeholders
|
||||
- Maintains context and nuance from discussion
|
||||
|
||||
### Content Type Selection
|
||||
- Correctly identifies appropriate content type (how-to, FAQ, decision record, wiki page)
|
||||
- Uses matching structure from reference documentation
|
||||
- Applies proper Notion markdown formatting
|
||||
|
||||
### Notion Integration
|
||||
- Searches for appropriate target location (wiki, decision log, etc.)
|
||||
- Creates well-structured pages with clear titles
|
||||
- Uses proper parent placement
|
||||
- Includes discoverable titles and metadata
|
||||
|
||||
### Quality Standards
|
||||
- Content is actionable and future-reference ready
|
||||
- Technical accuracy is preserved
|
||||
- Organization aids discoverability
|
||||
- Formatting enhances readability
|
||||
|
||||
## Creating New Evaluations
|
||||
|
||||
When adding Knowledge Capture evaluations:
|
||||
|
||||
1. **Use realistic conversation content** - Include actual technical details, decisions, or processes
|
||||
2. **Test different content types** - How-to guides, FAQs, decision records, meeting notes, learnings
|
||||
3. **Vary complexity** - Simple captures vs. complex technical discussions
|
||||
4. **Test discovery** - Finding the right wiki section or database
|
||||
5. **Include edge cases** - Unclear content types, minimal context, overlapping categories
|
||||
|
||||
## Example Success Criteria
|
||||
|
||||
**Good** (specific, testable):
|
||||
- "Structures content using How-To format with numbered steps"
|
||||
- "Preserves exact bash commands from conversation"
|
||||
- "Creates page with title format 'How to [Action]'"
|
||||
- "Places in Engineering Wiki → Deployment section"
|
||||
|
||||
**Bad** (vague, untestable):
|
||||
- "Creates good documentation"
|
||||
- "Uses appropriate structure"
|
||||
- "Saves to the right place"
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
{
|
||||
"name": "Save Conversation to Wiki",
|
||||
"skills": ["knowledge-capture"],
|
||||
"query": "Save this conversation about deploying our application to production to the team wiki",
|
||||
"context": "Preceding conversation contains discussion about deployment process, including steps, gotchas, and best practices",
|
||||
"expected_behavior": [
|
||||
"Extracts key information from conversation context (deployment steps, gotchas, best practices)",
|
||||
"Identifies content type as How-To Guide based on procedural nature",
|
||||
"Structures content using How-To structure: Overview → Prerequisites → Steps (numbered) → Verification → Troubleshooting → Related",
|
||||
"Organizes information into clear sections with proper headings",
|
||||
"Includes specific commands, configurations, or examples from conversation",
|
||||
"Adds context about why/when to use this process in Overview section",
|
||||
"Notes common issues and solutions mentioned in discussion in Troubleshooting section",
|
||||
"Uses Notion:notion-search to find team wiki location or asks user",
|
||||
"Creates page using Notion:notion-create-pages with structured content and appropriate parent",
|
||||
"Uses clear, descriptive title like 'How to Deploy to Production'",
|
||||
"Applies Notion markdown formatting (headings, code blocks, bullets)",
|
||||
"Suggests tags/categories for discoverability if wiki database"
|
||||
],
|
||||
"success_criteria": [
|
||||
"Content is structured using How-To format from SKILL.md content types",
|
||||
"Key points from conversation are captured accurately (not generic)",
|
||||
"Information is organized with proper Notion markdown (##, ###, bullets, code blocks)",
|
||||
"Specific technical details (commands, configs) are preserved from conversation",
|
||||
"Document is written for future reference with clear step-by-step instructions",
|
||||
"Title is searchable and descriptive (e.g., 'How to Deploy to Production')",
|
||||
"Page is placed in appropriate wiki location (general wiki or specific section)",
|
||||
"Uses correct tool name (Notion:notion-create-pages)"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
{
|
||||
"name": "Create Decision Record",
|
||||
"skills": ["knowledge-capture"],
|
||||
"query": "Document our decision to use PostgreSQL instead of MongoDB for our new service",
|
||||
"context": "User has just explained the decision with rationale, options considered, and trade-offs",
|
||||
"expected_behavior": [
|
||||
"Recognizes this as a decision record (architectural decision) from conversation context",
|
||||
"Uses Decision structure: Context → Decision → Rationale → Options Considered (with Pros/Cons) → Consequences → Implementation",
|
||||
"Extracts from context: decision made, options considered (PostgreSQL vs MongoDB), rationale, trade-offs",
|
||||
"Creates document with proper structure including Date, Status (Accepted), and Deciders",
|
||||
"Includes both positive and negative consequences (trade-offs) in Consequences section",
|
||||
"Uses Notion:notion-search to check if decision log database exists",
|
||||
"If database exists, asks whether to add there or create standalone page",
|
||||
"If creating in database, fetches schema using Notion:notion-fetch and sets properties: Decision title, Date, Status, Domain (Architecture), Deciders, Impact",
|
||||
"Uses Notion:notion-create-pages with parent: { data_source_id } for database or { page_id } for parent page",
|
||||
"Applies proper Notion markdown formatting with sections",
|
||||
"Suggests linking from architecture docs or project pages"
|
||||
],
|
||||
"success_criteria": [
|
||||
"Document follows Decision structure from SKILL.md content types",
|
||||
"All key sections present: Context, Decision, Rationale, Options Considered (with Pros/Cons for each), Consequences, Implementation",
|
||||
"Decision is clearly stated (PostgreSQL chosen over MongoDB)",
|
||||
"Options that were considered are documented with pros/cons structure",
|
||||
"Rationale explains why PostgreSQL was chosen based on conversation context",
|
||||
"Consequences include both positive (benefits) and negative (trade-offs)",
|
||||
"If in database, properties are set correctly from schema (Decision, Date, Status: Accepted, Domain: Architecture, Impact)",
|
||||
"Document is dated and has status 'Accepted'",
|
||||
"Uses correct tool names (Notion:notion-search, Notion:notion-fetch, Notion:notion-create-pages)"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,226 @@
|
||||
# Example: Conversation to FAQ
|
||||
|
||||
## User Request
|
||||
|
||||
> "Save this conversation about deployment troubleshooting to the FAQ"
|
||||
|
||||
**Context**: User just had a conversation explaining how to troubleshoot common deployment errors.
|
||||
|
||||
## Conversation Summary
|
||||
|
||||
The conversation covered:
|
||||
1. **Question**: "Why does deployment fail with 'port already in use' error?"
|
||||
2. **Answer**: Process from previous deployment still running, need to kill it
|
||||
3. **Question**: "How do I find and kill the process?"
|
||||
4. **Commands shared**: `lsof -ti:3000 | xargs kill -9` or use `pm2 restart app`
|
||||
5. **Question**: "What about 'cannot connect to database' errors?"
|
||||
6. **Answer**: Check database credentials, verify database is running, check network connectivity
|
||||
7. **Best practice**: Always check logs first (`pm2 logs` or `docker logs`)
|
||||
|
||||
## Workflow Execution
|
||||
|
||||
### Step 1: Identify Content Type
|
||||
|
||||
This is Q&A content → **FAQ Entry** format is appropriate
|
||||
|
||||
### Step 2: Structure FAQ Entries
|
||||
|
||||
Extract distinct Q&A pairs from conversation:
|
||||
|
||||
**FAQ 1**: Port already in use error
|
||||
**FAQ 2**: Cannot connect to database error
|
||||
**FAQ 3**: General troubleshooting approach
|
||||
|
||||
### Step 3: Determine Destination
|
||||
|
||||
```
|
||||
Notion:notion-search
|
||||
query: "FAQ deployment"
|
||||
query_type: "internal"
|
||||
```
|
||||
|
||||
Found: "Deployment FAQ" database in Engineering Docs
|
||||
|
||||
```
|
||||
Notion:notion-fetch
|
||||
id: "deployment-faq-database-id"
|
||||
```
|
||||
|
||||
**Schema**:
|
||||
- Question (title)
|
||||
- Category (select): Deployment, Configuration, Troubleshooting, etc.
|
||||
- Tags (multi_select)
|
||||
- Last Reviewed (date)
|
||||
|
||||
### Step 4: Create FAQ Entries
|
||||
|
||||
**FAQ Entry 1: Port Already in Use**
|
||||
|
||||
```
|
||||
Notion:notion-create-pages
|
||||
|
||||
parent: { data_source_id: "collection://faq-db-uuid" }
|
||||
|
||||
pages: [{
|
||||
properties: {
|
||||
"Question": "Why does deployment fail with 'port already in use' error?",
|
||||
"Category": "Troubleshooting",
|
||||
"Tags": "deployment, errors, ports",
|
||||
"date:Last Reviewed:start": "2025-10-14",
|
||||
"date:Last Reviewed:is_datetime": 0
|
||||
},
|
||||
content: "## Short Answer\n\nThe deployment port (usually 3000) is still occupied by a process from a previous deployment. You need to kill the existing process before deploying again.\n\n## Detailed Explanation\n\nWhen you deploy the application, it tries to bind to a specific port (e.g., port 3000). If a previous deployment didn't shut down cleanly, that process may still be running and holding the port. This prevents the new deployment from starting.\n\n**Common causes**:\n- Previous deployment crashed without cleanup\n- Manual `node` process started and forgotten\n- PM2 or other process manager didn't restart properly\n- Multiple deployments attempted simultaneously\n\n## Solution\n\n### Option 1: Kill the process using the port\n\n```bash\n# Find and kill process on port 3000\nlsof -ti:3000 | xargs kill -9\n```\n\nReplace `3000` with your application's port number.\n\n### Option 2: If using PM2\n\n```bash\n# Restart the application\npm2 restart app\n\n# Or delete and restart\npm2 delete app\npm2 start app.js --name app\n```\n\n### Option 3: Check all node processes\n\n```bash\n# List all node processes\nps aux | grep node\n\n# Kill specific process by PID\nkill -9 <PID>\n```\n\n## Prevention\n\n1. **Use process managers**: PM2, systemd, or Docker handle cleanup automatically\n2. **Graceful shutdown**: Implement proper shutdown handlers in your app\n3. **Health checks**: Monitor if previous deployment shut down before starting new one\n\n```javascript\n// Graceful shutdown example\nprocess.on('SIGTERM', () => {\n server.close(() => {\n console.log('Server closed');\n process.exit(0);\n });\n});\n```\n\n## Verification\n\nAfter killing the process, verify the port is free:\n\n```bash\nlsof -ti:3000\n# Should return nothing if port is free\n```\n\n## Related Questions\n- <mention-page url=\"...\">How do I check what's using a port?</mention-page>\n- <mention-page url=\"...\">How do I configure the application port?</mention-page>\n- <mention-page url=\"...\">PM2 deployment best practices</mention-page>\n\n## Last Updated\nOctober 14, 2025"
|
||||
}]
|
||||
```
|
||||
|
||||
**FAQ Entry 2: Database Connection Errors**
|
||||
|
||||
```
|
||||
Notion:notion-create-pages
|
||||
|
||||
parent: { data_source_id: "collection://faq-db-uuid" }
|
||||
|
||||
pages: [{
|
||||
properties: {
|
||||
"Question": "Why do I get 'cannot connect to database' errors during deployment?",
|
||||
"Category": "Troubleshooting",
|
||||
"Tags": "deployment, database, errors",
|
||||
"date:Last Reviewed:start": "2025-10-14",
|
||||
"date:Last Reviewed:is_datetime": 0
|
||||
},
|
||||
content: "## Short Answer\n\nDatabase connection errors usually mean either the database isn't running, credentials are incorrect, or there's a network connectivity issue. Check database status, verify credentials, and test connectivity.\n\n## Detailed Explanation\n\nThe application can't establish a connection to the database during startup. This prevents the application from initializing properly.\n\n**Common causes**:\n- Database service isn't running\n- Incorrect connection credentials\n- Network connectivity issues (firewall, security groups)\n- Database host/port misconfigured\n- Database is at connection limit\n- SSL/TLS configuration mismatch\n\n## Troubleshooting Steps\n\n### Step 1: Check database status\n\n```bash\n# For local PostgreSQL\npg_isready -h localhost -p 5432\n\n# For Docker\ndocker ps | grep postgres\n\n# For MongoDB\nmongosh --eval \"db.adminCommand('ping')\"\n```\n\n### Step 2: Verify credentials\n\nCheck your `.env` or configuration file:\n\n```bash\n# Common environment variables\nDB_HOST=localhost\nDB_PORT=5432\nDB_NAME=myapp_production\nDB_USER=myapp_user\nDB_PASSWORD=***********\n```\n\nTest connection manually:\n\n```bash\n# PostgreSQL\npsql -h $DB_HOST -p $DB_PORT -U $DB_USER -d $DB_NAME\n\n# MongoDB\nmongosh \"mongodb://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME\"\n```\n\n### Step 3: Check network connectivity\n\n```bash\n# Test if port is reachable\ntelnet $DB_HOST $DB_PORT\n\n# Or using nc\nnc -zv $DB_HOST $DB_PORT\n\n# Check firewall rules (if applicable)\nsudo iptables -L\n```\n\n### Step 4: Check application logs\n\n```bash\n# PM2 logs\npm2 logs app\n\n# Docker logs\ndocker logs container-name\n\n# Application logs\ntail -f /var/log/app/error.log\n```\n\nLook for specific error messages:\n- `ECONNREFUSED`: Database not running or wrong host/port\n- `Authentication failed`: Wrong credentials\n- `Timeout`: Network/firewall issue\n- `Too many connections`: Database connection limit reached\n\n## Solutions by Error Type\n\n### Database Not Running\n\n```bash\n# Start PostgreSQL\nsudo systemctl start postgresql\n\n# Start via Docker\ndocker start postgres-container\n```\n\n### Wrong Credentials\n\n1. Reset database password\n2. Update `.env` file\n3. Restart application\n\n### Connection Limit Reached\n\n```sql\n-- Check current connections (PostgreSQL)\nSELECT count(*) FROM pg_stat_activity;\n\n-- Increase max connections\nALTER SYSTEM SET max_connections = 200;\n```\n\n### SSL/TLS Issues\n\nAdd to connection string:\n```\nssl=true&sslmode=require\n```\n\nOr disable SSL for dev:\n```\nsslmode=disable\n```\n\n## Prevention\n\n1. **Connection pooling**: Limits concurrent connections\n```javascript\npool: {\n min: 2,\n max: 10\n}\n```\n\n2. **Health checks**: Verify database before starting app\n```javascript\nconst healthCheck = async () => {\n try {\n await db.raw('SELECT 1');\n console.log('Database connected');\n } catch (err) {\n console.error('Database connection failed:', err);\n process.exit(1);\n }\n};\n```\n\n3. **Retry logic**: Auto-reconnect on temporary failures\n```javascript\nretry: {\n max: 3,\n backoff: 1000\n}\n```\n\n4. **Environment validation**: Check all required env vars exist\n```javascript\nconst required = ['DB_HOST', 'DB_PORT', 'DB_NAME', 'DB_USER', 'DB_PASSWORD'];\nfor (const key of required) {\n if (!process.env[key]) {\n throw new Error(`Missing required env var: ${key}`);\n }\n}\n```\n\n## Related Questions\n- <mention-page url=\"...\">How do I configure database connection pooling?</mention-page>\n- <mention-page url=\"...\">Database backup and restore procedures</mention-page>\n- <mention-page url=\"...\">Database performance optimization</mention-page>\n\n## Last Updated\nOctober 14, 2025"
|
||||
}]
|
||||
```
|
||||
|
||||
**FAQ Entry 3: General Troubleshooting**
|
||||
|
||||
```
|
||||
Notion:notion-create-pages
|
||||
|
||||
parent: { data_source_id: "collection://faq-db-uuid" }
|
||||
|
||||
pages: [{
|
||||
properties: {
|
||||
"Question": "What's the first thing I should check when deployment fails?",
|
||||
"Category": "Troubleshooting",
|
||||
"Tags": "deployment, debugging, best-practices",
|
||||
"date:Last Reviewed:start": "2025-10-14",
|
||||
"date:Last Reviewed:is_datetime": 0
|
||||
},
|
||||
content: "## Short Answer\n\n**Always check the logs first.** Logs contain error messages that point you directly to the problem. Use `pm2 logs`, `docker logs`, or check your application's log files.\n\n## Detailed Explanation\n\nLogs are your first and most important debugging tool. They show:\n- Exact error messages\n- Stack traces\n- Timing information\n- Configuration issues\n- Dependency problems\n\nMost deployment issues can be diagnosed and fixed by reading the logs carefully.\n\n## How to Check Logs\n\n### PM2\n\n```bash\n# View all logs\npm2 logs\n\n# View logs for specific app\npm2 logs app-name\n\n# View only errors\npm2 logs --err\n\n# Follow logs in real-time\npm2 logs --lines 100\n```\n\n### Docker\n\n```bash\n# View logs\ndocker logs container-name\n\n# Follow logs\ndocker logs -f container-name\n\n# Last 100 lines\ndocker logs --tail 100 container-name\n\n# With timestamps\ndocker logs -t container-name\n```\n\n### Application Logs\n\n```bash\n# Tail application logs\ntail -f /var/log/app/app.log\ntail -f /var/log/app/error.log\n\n# Search logs for errors\ngrep -i error /var/log/app/*.log\n\n# View logs with context\ngrep -B 5 -A 5 \"ERROR\" app.log\n```\n\n## Systematic Troubleshooting Approach\n\n### 1. Check the logs\n- Read error messages carefully\n- Note the exact error type and message\n- Check timestamps to find when error occurred\n\n### 2. Verify configuration\n- Environment variables set correctly?\n- Configuration files present and valid?\n- Paths and file permissions correct?\n\n### 3. Check dependencies\n- All packages installed? (`node_modules` present?)\n- Correct versions installed?\n- Any native module compilation errors?\n\n### 4. Verify environment\n- Required services running (database, Redis, etc.)?\n- Ports available?\n- Network connectivity working?\n\n### 5. Test components individually\n- Can you connect to database manually?\n- Can you run application locally?\n- Do health check endpoints work?\n\n### 6. Check recent changes\n- What changed since last successful deployment?\n- New dependencies added?\n- Configuration modified?\n- Environment differences?\n\n## Common Error Patterns\n\n### \"Module not found\"\n```bash\n# Solution: Install dependencies\nnpm install\n# or\nnpm ci\n```\n\n### \"Permission denied\"\n```bash\n# Solution: Fix file permissions\nchmod +x start.sh\nsudo chown -R appuser:appuser /app\n```\n\n### \"Address already in use\"\n```bash\n# Solution: Kill process on port\nlsof -ti:3000 | xargs kill -9\n```\n\n### \"Cannot connect to...\"\n```bash\n# Solution: Verify service is running and reachable\ntelnet service-host port\n```\n\n## Debugging Tools\n\n### Log Aggregation\n- **PM2**: Built-in log management\n- **Docker**: Centralized logging with log drivers\n- **ELK Stack**: Elasticsearch, Logstash, Kibana for large scale\n- **CloudWatch**: For AWS deployments\n\n### Monitoring\n- **PM2 Monit**: `pm2 monit` for real-time metrics\n- **Docker Stats**: `docker stats` for resource usage\n- **System metrics**: `top`, `htop` for CPU/memory\n\n### Network Debugging\n```bash\n# Check open connections\nnetstat -tulpn\n\n# Check specific port\nlsof -i :3000\n\n# Test connectivity\ncurl http://localhost:3000/health\n```\n\n## When to Escalate\n\nEscalate to senior team member if:\n- Error message is cryptic and not Google-able\n- Problem persists after trying obvious solutions\n- Production is affected\n- Data integrity may be compromised\n- Security-related errors\n\n## Prevention\n\n1. **Automated health checks** before deployment\n2. **Staged deployments** (dev → staging → production)\n3. **Rollback plan** ready for quick recovery\n4. **Monitoring and alerts** for early problem detection\n5. **Deployment checklist** to ensure all steps followed\n\n## Related Questions\n- <mention-page url=\"...\">How do I set up log aggregation?</mention-page>\n- <mention-page url=\"...\">Deployment checklist and best practices</mention-page>\n- <mention-page url=\"...\">How to roll back a failed deployment?</mention-page>\n\n## Last Updated\nOctober 14, 2025"
|
||||
}]
|
||||
```
|
||||
|
||||
### Step 5: Update FAQ Index
|
||||
|
||||
```
|
||||
Notion:notion-fetch
|
||||
id: "faq-index-page-id"
|
||||
```
|
||||
|
||||
```
|
||||
Notion:notion-update-page
|
||||
page_id: "faq-index-page-id"
|
||||
command: "insert_content_after"
|
||||
selection_with_ellipsis: "## Deployment & Troubleshooting..."
|
||||
new_str: "
|
||||
- <mention-page url=\"...\">Why does deployment fail with 'port already in use' error?</mention-page>
|
||||
- <mention-page url=\"...\">Why do I get 'cannot connect to database' errors?</mention-page>
|
||||
- <mention-page url=\"...\">What's the first thing I should check when deployment fails?</mention-page>
|
||||
"
|
||||
```
|
||||
|
||||
## Summary Provided to User
|
||||
|
||||
```markdown
|
||||
## FAQ Entries Created ✅
|
||||
|
||||
### Conversation Captured
|
||||
Transformed deployment troubleshooting conversation into 3 comprehensive FAQ entries.
|
||||
|
||||
### FAQ Entries Created
|
||||
|
||||
1. **Port Already in Use Error**
|
||||
- Problem: Deployment fails due to occupied port
|
||||
- Solutions: Kill process, use PM2, check node processes
|
||||
- Prevention: Use process managers, graceful shutdown
|
||||
- Link: <mention-page url="...">Port already in use FAQ</mention-page>
|
||||
|
||||
2. **Database Connection Errors**
|
||||
- Problem: Cannot connect to database during deployment
|
||||
- Troubleshooting: 4-step systematic approach
|
||||
- Solutions: By error type (credentials, network, limits)
|
||||
- Prevention: Connection pooling, health checks, retry logic
|
||||
- Link: <mention-page url="...">Database connection FAQ</mention-page>
|
||||
|
||||
3. **General Troubleshooting Approach**
|
||||
- Best practice: Always check logs first
|
||||
- Tools: PM2 logs, Docker logs, application logs
|
||||
- Systematic approach: 6-step debugging process
|
||||
- Common errors: Module not found, permissions, ports
|
||||
- Link: <mention-page url="...">Troubleshooting first steps FAQ</mention-page>
|
||||
|
||||
### Content Structure
|
||||
|
||||
Each FAQ includes:
|
||||
✅ Short answer (quick reference)
|
||||
✅ Detailed explanation (full context)
|
||||
✅ Multiple solution options
|
||||
✅ Code examples and commands
|
||||
✅ Prevention strategies
|
||||
✅ Links to related FAQs
|
||||
✅ Last updated date
|
||||
|
||||
### Database Integration
|
||||
|
||||
- ✅ Added to FAQ database (not standalone pages)
|
||||
- ✅ Properties set: Category (Troubleshooting), Tags, Date
|
||||
- ✅ FAQ index page updated with links
|
||||
- ✅ Cross-references between related questions
|
||||
|
||||
### Value Added
|
||||
|
||||
**From conversation** → **To structured knowledge**:
|
||||
- Casual Q&A → Professional FAQ entries
|
||||
- Implicit knowledge → Explicit documentation
|
||||
- One-time help → Reusable resource
|
||||
- 5-minute conversation → Permanent team knowledge
|
||||
|
||||
**Future benefit**:
|
||||
- Team can self-serve on common issues
|
||||
- New team members can onboard faster
|
||||
- Reduces repeated questions
|
||||
- Improves troubleshooting speed
|
||||
|
||||
**Knowledge captured and preserved! 📚**
|
||||
```
|
||||
|
||||
## Key Features Demonstrated
|
||||
|
||||
### Content Extraction
|
||||
- Identified distinct Q&A pairs from conversation
|
||||
- Extracted commands, solutions, and best practices
|
||||
- Preserved troubleshooting workflows
|
||||
|
||||
### FAQ Structure
|
||||
- Short answer for quick reference
|
||||
- Detailed explanation for understanding
|
||||
- Multiple solutions (Options 1, 2, 3)
|
||||
- Code examples with comments
|
||||
- Prevention strategies
|
||||
- Related questions linking
|
||||
|
||||
### Database Integration
|
||||
- Created in FAQ database (not standalone)
|
||||
- Set appropriate properties (category, tags, date)
|
||||
- Updated index page with links
|
||||
- Cross-referenced related questions
|
||||
|
||||
### Value Transformation
|
||||
- Converted informal conversation to professional docs
|
||||
- Added structure, examples, and prevention tips
|
||||
- Made knowledge searchable and discoverable
|
||||
- Created permanent team resource
|
||||
|
||||
Perfect for: FAQ creation, knowledge preservation, team documentation
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
# Example: Decision Record Capture
|
||||
|
||||
**User Request**: "Document our decision to move from REST to GraphQL API"
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Extract Decision from Context
|
||||
From conversation, identified:
|
||||
- **Decision**: Migrate customer-facing API from REST to GraphQL
|
||||
- **Context**: REST endpoints becoming unwieldy (50+ endpoints)
|
||||
- **Alternatives**: Keep REST, try gRPC, adopt GraphQL
|
||||
- **Rationale**: Better client experience, type safety, single endpoint
|
||||
|
||||
### 2. Find Decision Log
|
||||
```
|
||||
Notion:notion-search
|
||||
query: "architecture decisions" or "ADR"
|
||||
```
|
||||
|
||||
Found: "Architecture Decision Records" database
|
||||
|
||||
### 3. Fetch Schema
|
||||
```
|
||||
Notion:notion-fetch
|
||||
```
|
||||
|
||||
Got properties: Decision (title), Date, Status, Domain, Impact, Deciders, Stakeholders
|
||||
|
||||
### 4. Create Decision Record
|
||||
```
|
||||
Notion:notion-create-pages
|
||||
parent: { data_source_id: "decision-log-collection-id" }
|
||||
pages: [{
|
||||
properties: {
|
||||
"Decision": "Migrate to GraphQL API",
|
||||
"date:Date:start": "2025-10-16",
|
||||
"date:Date:is_datetime": 0,
|
||||
"Status": "Accepted",
|
||||
"Domain": "Architecture",
|
||||
"Impact": "High"
|
||||
},
|
||||
content: "[Full decision record with context, rationale, alternatives...]"
|
||||
}]
|
||||
```
|
||||
|
||||
**Content sample**:
|
||||
|
||||
```markdown
|
||||
# Migrate Customer-Facing API to GraphQL
|
||||
|
||||
## Context
|
||||
Our REST API has grown to 50+ endpoints with inconsistent patterns. Frontend and mobile teams request new endpoints frequently, leading to:
|
||||
- API bloat and maintenance burden
|
||||
- Over-fetching/under-fetching data
|
||||
- Slow iteration on client features
|
||||
- Inconsistent error handling
|
||||
|
||||
## Decision
|
||||
Migrate customer-facing API from REST to GraphQL while maintaining REST for internal services.
|
||||
|
||||
## Rationale
|
||||
**Why GraphQL**:
|
||||
- Clients fetch exactly what they need (no over/under-fetching)
|
||||
- Single endpoint, self-documenting schema
|
||||
- Type safety with code generation
|
||||
- Better developer experience
|
||||
- Industry standard for client-facing APIs
|
||||
|
||||
## Options Considered
|
||||
|
||||
### Option A: Keep REST (Status Quo)
|
||||
**Pros**: No migration cost, team familiar
|
||||
**Cons**: Doesn't solve core problems, maintenance keeps growing
|
||||
**Decision**: Rejected - doesn't address root cause
|
||||
|
||||
### Option B: gRPC
|
||||
**Pros**: Performance, strong typing
|
||||
**Cons**: Browser support issues, steeper learning curve, not designed for client-facing
|
||||
**Decision**: Rejected - better for internal services
|
||||
|
||||
### Option C: GraphQL
|
||||
**Pros**: Solves over/under-fetching, great DX, strong ecosystem
|
||||
**Cons**: Learning curve, caching complexity, migration effort
|
||||
**Decision**: **Accepted**
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive**:
|
||||
- Faster frontend/mobile development
|
||||
- Reduced API maintenance burden
|
||||
- Better type safety and tooling
|
||||
- Single endpoint simplifies deployment
|
||||
|
||||
**Negative**:
|
||||
- 3-4 month migration timeline
|
||||
- Team needs training
|
||||
- Need to solve caching strategy
|
||||
- Monitoring/debugging patterns different
|
||||
|
||||
## Implementation Plan
|
||||
1. GraphQL server setup (Apollo Server)
|
||||
2. Schema design workshop
|
||||
3. Gradual migration (start with new features)
|
||||
4. Dual-run period (both REST and GraphQL)
|
||||
5. Deprecate old REST endpoints
|
||||
|
||||
**Timeline**: Start Q4 2025, complete Q1 2026
|
||||
**Owner**: Backend team lead
|
||||
|
||||
## Success Metrics
|
||||
- API response times improve 30%
|
||||
- Client fetch efficiency (less data transferred)
|
||||
- Reduced new endpoint requests
|
||||
- Developer satisfaction scores
|
||||
```
|
||||
|
||||
### 5. Make Discoverable
|
||||
Added link from Architecture Wiki and notified team in Slack.
|
||||
|
||||
## Key Success Factors
|
||||
- Captured decision while context fresh
|
||||
- Documented alternatives considered
|
||||
- Included both pros and cons
|
||||
- Clear implementation plan
|
||||
- Saved to decision log for future reference
|
||||
- Made discoverable for team
|
||||
@@ -0,0 +1,118 @@
|
||||
# Example: How-To Guide from Discussion
|
||||
|
||||
**User Request**: "Save our discussion about deploying to production as a how-to guide"
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Extract Content from Chat
|
||||
From conversation, identified:
|
||||
- Deployment prerequisites
|
||||
- Step-by-step procedure
|
||||
- Common issues and solutions
|
||||
- Best practices and tips
|
||||
|
||||
### 2. Structure as How-To
|
||||
Organized into:
|
||||
- Overview & prerequisites
|
||||
- Numbered deployment steps
|
||||
- Verification steps
|
||||
- Troubleshooting section
|
||||
- Related resources
|
||||
|
||||
### 3. Find Location
|
||||
```
|
||||
Notion:notion-search
|
||||
query: "deployment documentation"
|
||||
```
|
||||
Found: Engineering Wiki → Deployment section
|
||||
|
||||
### 4. Create Guide
|
||||
```
|
||||
Notion:notion-create-pages
|
||||
parent: { page_id: "deployment-section-id" }
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
```markdown
|
||||
# How to Deploy to Production
|
||||
|
||||
## Overview
|
||||
Production deployment using GitHub Actions with zero-downtime rolling updates.
|
||||
**Time Required**: 15-20 minutes | **Complexity**: Intermediate
|
||||
|
||||
## Prerequisites
|
||||
- [ ] PR approved and merged to main
|
||||
- [ ] All CI tests passing
|
||||
- [ ] Database migrations reviewed
|
||||
- [ ] Feature flags configured
|
||||
|
||||
## Deployment Steps
|
||||
|
||||
1. **Verify main branch is ready**
|
||||
```bash
|
||||
git checkout main && git pull
|
||||
```
|
||||
|
||||
2. **Tag release**
|
||||
```bash
|
||||
git tag -a v1.2.3 -m "Release v1.2.3"
|
||||
git push origin v1.2.3
|
||||
```
|
||||
|
||||
3. **Trigger deployment**
|
||||
- GitHub Actions auto-starts from tag push
|
||||
- Monitor: https://github.com/org/repo/actions
|
||||
|
||||
4. **Database migrations** (if needed)
|
||||
- Auto-run in GitHub Actions
|
||||
- Check logs for completion
|
||||
|
||||
5. **Verify deployment**
|
||||
- Wait for health checks (2-3 min)
|
||||
- Test key endpoints
|
||||
- Check error rates in Datadog
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] All pods healthy in k8s dashboard
|
||||
- [ ] Error rate < 0.1% in last 10 min
|
||||
- [ ] Response time p95 < 500ms
|
||||
- [ ] Test login flow
|
||||
- [ ] Check Slack #alerts channel
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Health checks failing**
|
||||
→ Check pod logs: `kubectl logs -f deployment/api -n production`
|
||||
|
||||
**Migration errors**
|
||||
→ Rollback: Revert tag, migrations auto-rollback
|
||||
|
||||
**High error rate**
|
||||
→ Emergency rollback: Previous tag auto-deploys via GitHub Actions
|
||||
|
||||
## Best Practices
|
||||
- Deploy during low-traffic hours (2-4am PST)
|
||||
- Have 2 engineers available
|
||||
- Monitor for 30 min post-deploy
|
||||
- Update #engineering Slack with deploy notice
|
||||
|
||||
## Related Docs
|
||||
- <mention-page url="...">Rollback Procedure</mention-page>
|
||||
- <mention-page url="...">Database Migration Guide</mention-page>
|
||||
```
|
||||
|
||||
### 5. Make Discoverable
|
||||
```
|
||||
Notion:notion-update-page
|
||||
page_id: "engineering-wiki-homepage"
|
||||
command: "insert_content_after"
|
||||
```
|
||||
Added link in Engineering Wiki → How-To Guides section
|
||||
|
||||
## Key Success Factors
|
||||
- Captured tribal knowledge from discussion
|
||||
- Structured as actionable steps
|
||||
- Included troubleshooting from experience
|
||||
- Made discoverable by linking from wiki index
|
||||
- Added metadata (time, complexity)
|
||||
@@ -0,0 +1,112 @@
|
||||
# Database Best Practices
|
||||
|
||||
General guidance for creating and maintaining knowledge capture databases.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Keep It Simple
|
||||
- Start with core properties
|
||||
- Add more only when needed
|
||||
- Don't over-engineer
|
||||
|
||||
### 2. Use Consistent Naming
|
||||
- Title property for main identifier
|
||||
- Status for lifecycle tracking
|
||||
- Tags for flexible categorization
|
||||
- Owner for accountability
|
||||
|
||||
### 3. Include Metadata
|
||||
- Created/Updated timestamps
|
||||
- Owner or maintainer
|
||||
- Last reviewed dates
|
||||
- Status indicators
|
||||
|
||||
### 4. Enable Discovery
|
||||
- Use tags liberally
|
||||
- Create helpful views
|
||||
- Link related content
|
||||
- Use clear titles
|
||||
|
||||
### 5. Plan for Scale
|
||||
- Consider filters early
|
||||
- Use relations for connections
|
||||
- Think about search
|
||||
- Organize with categories
|
||||
|
||||
## Creating a Database
|
||||
|
||||
### Using `Notion:notion-create-database`
|
||||
|
||||
Example for documentation database:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"parent": {"page_id": "wiki-page-id"},
|
||||
"title": [{"text": {"content": "Team Documentation"}}],
|
||||
"properties": {
|
||||
"Type": {
|
||||
"select": {
|
||||
"options": [
|
||||
{"name": "How-To", "color": "blue"},
|
||||
{"name": "Concept", "color": "green"},
|
||||
{"name": "Reference", "color": "gray"},
|
||||
{"name": "FAQ", "color": "yellow"}
|
||||
]
|
||||
}
|
||||
},
|
||||
"Category": {
|
||||
"select": {
|
||||
"options": [
|
||||
{"name": "Engineering", "color": "red"},
|
||||
{"name": "Product", "color": "purple"},
|
||||
{"name": "Design", "color": "pink"}
|
||||
]
|
||||
}
|
||||
},
|
||||
"Tags": {"multi_select": {"options": []}},
|
||||
"Owner": {"people": {}},
|
||||
"Status": {
|
||||
"select": {
|
||||
"options": [
|
||||
{"name": "Draft", "color": "gray"},
|
||||
{"name": "Final", "color": "green"},
|
||||
{"name": "Deprecated", "color": "red"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Fetching Database Schema
|
||||
|
||||
Before creating pages, always fetch database to get schema:
|
||||
|
||||
```
|
||||
Notion:notion-fetch
|
||||
id: "database-url-or-id"
|
||||
```
|
||||
|
||||
This returns the exact property names and types to use.
|
||||
|
||||
## Database Selection Guide
|
||||
|
||||
| Need | Use This Database |
|
||||
|------|-------------------|
|
||||
| General documentation | [Documentation Database](documentation-database.md) |
|
||||
| Track decisions | [Decision Log](decision-log-database.md) |
|
||||
| Q&A knowledge base | [FAQ Database](faq-database.md) |
|
||||
| Team-specific content | [Team Wiki](team-wiki-database.md) |
|
||||
| Step-by-step guides | [How-To Guide Database](how-to-guide-database.md) |
|
||||
| Incident/project learnings | [Learning Database](learning-database.md) |
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Start with general documentation database** - most flexible
|
||||
2. **Add specialized databases** as needs emerge (FAQ, Decisions)
|
||||
3. **Use relations** to connect related docs
|
||||
4. **Create views** for common use cases
|
||||
5. **Review properties** quarterly - remove unused ones
|
||||
6. **Document the schema** in database description
|
||||
7. **Train team** on property usage and conventions
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# Decision Log Database (ADR - Architecture Decision Records)
|
||||
|
||||
**Purpose**: Track important decisions with context and rationale.
|
||||
|
||||
## Schema
|
||||
|
||||
| Property | Type | Options | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| **Decision** | title | - | What was decided |
|
||||
| **Date** | date | - | When decision was made |
|
||||
| **Status** | select | Proposed, Accepted, Superseded, Deprecated | Current decision status |
|
||||
| **Domain** | select | Architecture, Product, Business, Design, Operations | Decision category |
|
||||
| **Impact** | select | High, Medium, Low | Expected impact level |
|
||||
| **Deciders** | people | - | Who made the decision |
|
||||
| **Stakeholders** | people | - | Who's affected by decision |
|
||||
| **Related Decisions** | relation | Links to other decisions | Context and dependencies |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
Create decision records with properties:
|
||||
{
|
||||
"Decision": "Use PostgreSQL for Primary Database",
|
||||
"Date": "2025-10-15",
|
||||
"Status": "Accepted",
|
||||
"Domain": "Architecture",
|
||||
"Impact": "High",
|
||||
"Deciders": [tech_lead, architect],
|
||||
"Stakeholders": [eng_team]
|
||||
}
|
||||
```
|
||||
|
||||
## Content Template
|
||||
|
||||
Each decision page should include:
|
||||
- **Context**: Why this decision was needed
|
||||
- **Decision**: What was decided
|
||||
- **Rationale**: Why this option was chosen
|
||||
- **Options Considered**: Alternatives and trade-offs
|
||||
- **Consequences**: Expected outcomes (positive and negative)
|
||||
- **Implementation**: How decision will be executed
|
||||
|
||||
## Views
|
||||
|
||||
**Recent Decisions**: Sort by Date descending
|
||||
**Active Decisions**: Filter where Status = "Accepted"
|
||||
**By Domain**: Group by Domain
|
||||
**High Impact**: Filter where Impact = "High"
|
||||
**Pending**: Filter where Status = "Proposed"
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Document immediately**: Record decisions when made, while context is fresh
|
||||
2. **Include alternatives**: Show what was considered and why it wasn't chosen
|
||||
3. **Track superseded decisions**: Update status when decisions change
|
||||
4. **Link related decisions**: Use relations to show dependencies
|
||||
5. **Review periodically**: Check if old decisions are still valid
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# General Documentation Database
|
||||
|
||||
**Purpose**: Store all types of documentation in a searchable, organized database.
|
||||
|
||||
## Schema
|
||||
|
||||
| Property | Type | Options | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| **Title** | title | - | Document name |
|
||||
| **Type** | select | How-To, Concept, Reference, FAQ, Decision, Post-Mortem | Categorize content type |
|
||||
| **Category** | select | Engineering, Product, Design, Operations, General | Organize by department/topic |
|
||||
| **Tags** | multi_select | - | Additional categorization (languages, tools, topics) |
|
||||
| **Status** | select | Draft, In Review, Final, Deprecated | Track document lifecycle |
|
||||
| **Owner** | people | - | Document maintainer |
|
||||
| **Created** | created_time | - | Auto-populated creation date |
|
||||
| **Last Updated** | last_edited_time | - | Auto-populated last edit |
|
||||
| **Last Reviewed** | date | - | Manual review tracking |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
Create pages with properties:
|
||||
{
|
||||
"Title": "How to Deploy to Production",
|
||||
"Type": "How-To",
|
||||
"Category": "Engineering",
|
||||
"Tags": "deployment, production, DevOps",
|
||||
"Status": "Final",
|
||||
"Owner": [current_user],
|
||||
"Last Reviewed": "2025-10-01"
|
||||
}
|
||||
```
|
||||
|
||||
## Views
|
||||
|
||||
**By Type**: Group by Type property
|
||||
**By Category**: Group by Category property
|
||||
**Recent Updates**: Sort by Last Updated descending
|
||||
**Needs Review**: Filter where Last Reviewed > 90 days ago
|
||||
**Draft Docs**: Filter where Status = "Draft"
|
||||
|
||||
## Creating This Database
|
||||
|
||||
Use `Notion:notion-create-database`:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"parent": {"page_id": "wiki-page-id"},
|
||||
"title": [{"text": {"content": "Team Documentation"}}],
|
||||
"properties": {
|
||||
"Type": {
|
||||
"select": {
|
||||
"options": [
|
||||
{"name": "How-To", "color": "blue"},
|
||||
{"name": "Concept", "color": "green"},
|
||||
{"name": "Reference", "color": "gray"},
|
||||
{"name": "FAQ", "color": "yellow"}
|
||||
]
|
||||
}
|
||||
},
|
||||
"Category": {
|
||||
"select": {
|
||||
"options": [
|
||||
{"name": "Engineering", "color": "red"},
|
||||
{"name": "Product", "color": "purple"},
|
||||
{"name": "Design", "color": "pink"}
|
||||
]
|
||||
}
|
||||
},
|
||||
"Tags": {"multi_select": {"options": []}},
|
||||
"Owner": {"people": {}},
|
||||
"Status": {
|
||||
"select": {
|
||||
"options": [
|
||||
{"name": "Draft", "color": "gray"},
|
||||
{"name": "Final", "color": "green"},
|
||||
{"name": "Deprecated", "color": "red"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with this schema** - most flexible for general documentation
|
||||
2. **Use relations** to connect related docs
|
||||
3. **Create views** for common use cases
|
||||
4. **Review properties** quarterly - remove unused ones
|
||||
5. **Document the schema** in database description
|
||||
6. **Train team** on property usage and conventions
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# FAQ Database
|
||||
|
||||
**Purpose**: Organize frequently asked questions with answers.
|
||||
|
||||
## Schema
|
||||
|
||||
| Property | Type | Options | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| **Question** | title | - | The question being asked |
|
||||
| **Category** | select | Product, Engineering, Support, HR, General | Question topic |
|
||||
| **Tags** | multi_select | - | Specific topics (auth, billing, onboarding, etc.) |
|
||||
| **Answer Type** | select | Quick Answer, Detailed Guide, Link to Docs | Response format |
|
||||
| **Last Reviewed** | date | - | When answer was verified |
|
||||
| **Helpful Count** | number | - | Track usefulness (optional) |
|
||||
| **Audience** | select | Internal, External, All | Who should see this |
|
||||
| **Related Questions** | relation | Links to related FAQs | Connect similar topics |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
Create FAQ entries with properties:
|
||||
{
|
||||
"Question": "How do I reset my password?",
|
||||
"Category": "Support",
|
||||
"Tags": "authentication, password, login",
|
||||
"Answer Type": "Quick Answer",
|
||||
"Last Reviewed": "2025-10-01",
|
||||
"Audience": "External"
|
||||
}
|
||||
```
|
||||
|
||||
## Content Template
|
||||
|
||||
Each FAQ page should include:
|
||||
- **Short Answer**: 1-2 sentence quick response
|
||||
- **Detailed Explanation**: Full answer with context
|
||||
- **Steps** (if applicable): Numbered procedure
|
||||
- **Screenshots** (if helpful): Visual guidance
|
||||
- **Related Questions**: Links to similar FAQs
|
||||
- **Additional Resources**: External docs or videos
|
||||
|
||||
## Views
|
||||
|
||||
**By Category**: Group by Category
|
||||
**Recently Updated**: Sort by Last Reviewed descending
|
||||
**Needs Review**: Filter where Last Reviewed > 180 days ago
|
||||
**External FAQs**: Filter where Audience contains "External"
|
||||
**Popular**: Sort by Helpful Count descending (if tracking)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use clear questions**: Write questions as users would ask them
|
||||
2. **Provide quick answers**: Lead with the direct answer, then elaborate
|
||||
3. **Link related FAQs**: Help users discover related information
|
||||
4. **Review regularly**: Keep answers current and accurate
|
||||
5. **Track what's helpful**: Use feedback to improve frequently accessed FAQs
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
# How-To Guide Database
|
||||
|
||||
**Purpose**: Procedural documentation for common tasks.
|
||||
|
||||
## Schema
|
||||
|
||||
| Property | Type | Options | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| **Title** | title | - | "How to [Task]" |
|
||||
| **Complexity** | select | Beginner, Intermediate, Advanced | Skill level required |
|
||||
| **Time Required** | number | - | Estimated minutes to complete |
|
||||
| **Prerequisites** | relation | Links to other guides | Required knowledge |
|
||||
| **Category** | select | Development, Deployment, Testing, Tools | Task category |
|
||||
| **Last Tested** | date | - | When procedure was verified |
|
||||
| **Tags** | multi_select | - | Technology/tool tags |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
Create how-to guides with properties:
|
||||
{
|
||||
"Title": "How to Set Up Local Development Environment",
|
||||
"Complexity": "Beginner",
|
||||
"Time Required": 30,
|
||||
"Category": "Development",
|
||||
"Last Tested": "2025-10-01",
|
||||
"Tags": "setup, environment, docker"
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use consistent naming**: Always start with "How to..."
|
||||
2. **Test procedures**: Verify steps work before publishing
|
||||
3. **Include time estimates**: Help users plan their time
|
||||
4. **Link prerequisites**: Make dependencies clear
|
||||
5. **Update regularly**: Re-test procedures when tools/systems change
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# Learning/Post-Mortem Database
|
||||
|
||||
**Purpose**: Capture learnings from incidents, projects, or experiences.
|
||||
|
||||
## Schema
|
||||
|
||||
| Property | Type | Options | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| **Title** | title | - | Event or project name |
|
||||
| **Date** | date | - | When it happened |
|
||||
| **Type** | select | Incident, Project, Experiment, Retrospective | Learning type |
|
||||
| **Severity** | select | Critical, Major, Minor | Impact level (for incidents) |
|
||||
| **Team** | people | - | Who was involved |
|
||||
| **Key Learnings** | number | - | Count of learnings |
|
||||
| **Action Items** | relation | Links to tasks | Follow-up actions |
|
||||
|
||||
## Content Template
|
||||
|
||||
Each learning page should include:
|
||||
- **What Happened**: Situation description
|
||||
- **What Went Well**: Success factors
|
||||
- **What Didn't Go Well**: Problems encountered
|
||||
- **Root Causes**: Why things happened
|
||||
- **Learnings**: Key takeaways
|
||||
- **Action Items**: Improvements to implement
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Blameless approach**: Focus on systems and processes, not individuals
|
||||
2. **Document quickly**: Capture while memory is fresh
|
||||
3. **Identify root causes**: Go beyond surface-level problems
|
||||
4. **Create action items**: Turn learnings into improvements
|
||||
5. **Follow up**: Track that action items are completed
|
||||
6. **Share widely**: Make learnings accessible to entire team
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Team Wiki Database
|
||||
|
||||
**Purpose**: Centralized team knowledge and resources.
|
||||
|
||||
## Schema
|
||||
|
||||
| Property | Type | Options | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
| **Title** | title | - | Page name |
|
||||
| **Section** | select | Getting Started, Processes, Tools, Reference, Onboarding | Wiki organization |
|
||||
| **Tags** | multi_select | - | Topic tags |
|
||||
| **Owner** | people | - | Page maintainer |
|
||||
| **Last Updated** | last_edited_time | - | Auto-tracked |
|
||||
| **Visibility** | select | Public, Team Only, Confidential | Access level |
|
||||
|
||||
## Usage
|
||||
|
||||
Use for team-specific documentation that doesn't fit other databases.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Organize by sections**: Use clear top-level organization
|
||||
2. **Assign owners**: Every page should have a maintainer
|
||||
3. **Control visibility**: Set appropriate access levels
|
||||
4. **Link extensively**: Connect related pages
|
||||
5. **Keep current**: Regular reviews to remove outdated content
|
||||
|
||||
Reference in New Issue
Block a user