メニュー
Knowledge Base Creation: Searchable wikis, internal documentation portals, knowledge management systems
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills --skill knowledge-baseコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SOC 職業分類に基づく
SKILL.md を表示中
| name | knowledge-base |
| description | Knowledge Base Creation: Searchable wikis, internal documentation portals, knowledge management systems |
| metadata | {"author":"cosmicstack-labs","version":"1.0.0","category":"development","tags":["knowledge-base","wiki","internal-docs","knowledge-management","documentation"]} |
Build searchable, maintainable knowledge bases that your team actually uses — turning tribal knowledge into organizational assets.
A knowledge base is never "done." It requires ongoing investment: content creation, curation, cleanup, and promotion. Treat it like a product with a roadmap, owners, and metrics.
If users can't find what they need in 2-3 searches, the knowledge base has failed. Invest in search quality, metadata, tagging, and cross-referencing before adding more content.
The easier it is to write and publish, the more content you'll get. Support markdown, provide templates, reduce review friction for minor edits, and celebrate contributors.
Organize content in categories users naturally think in. Use clear titles, descriptive summaries, consistent formatting, and plenty of internal links.
Track search success rates, popular content, stale pages, and user feedback. Use data to decide what to improve, archive, or create next.
| Level | Content | Search | Maintenance |
|---|
| Contribution |
|---|
| Governance |
|---|
| 1: Graveyard | Random docs, no structure | None (browse only) | Never updated | No process | No owners |
| 2: Collection | Some structure, inconsistent | Basic text search | Updated reactively | A few contributors | Unclear ownership |
| 3: Organized | Taxonomy defined, templates used | Tagged + full-text search | Regular reviews | Active contributors | Defined content owners |
| 4: Curated | Reviewed content, versioned | Faceted + filtered search | Scheduled audits | Contributor workflows | Editorial board |
| 5: Living | Feedback-driven, analytics-informed | Semantic + AI-assisted | Continuous improvement | Embedded in workflows | Metrics-driven governance |
Target: Level 3 for most teams. Level 4 for customer-facing or compliance-relevant knowledge bases.
| Platform | Best For | Key Features | Limitations | Hosting |
|---|---|---|---|---|
| GitBook | Developer docs, API docs | Git-synced, versioned, search, multi-language | Pricing at scale | Cloud or self-hosted |
| Notion | Internal wikis, team knowledge | Rich editor, databases, templates, AI search | Export limitations, performance | Cloud only |
| Docusaurus | Open source project docs | React-based, versioned, MDX, search plugins | Requires developer setup | Static site (any host) |
| MkDocs | Python projects, simple docs | Python ecosystem, Material theme, plugins | Less flexible than Docusaurus | Static site (any host) |
| Confluence | Enterprise internal docs | Deep Jira integration, permissions, analytics | Heavy, expensive, poor search | Cloud or self-hosted |
| Obsidian Publish | Personal knowledge, Zettelkasten | Graph view, backlinks, local-first | Limited collaboration | Cloud (paid) |
| Outline | Internal wikis (mid-size teams) | Markdown-native, fast, Slack integration | Smaller ecosystem | Cloud or self-hosted |
## Platform Decision Matrix
| Requirement | GitBook | Notion | Docusaurus | MkDocs | Confluence |
|-------------|---------|--------|------------|--------|------------|
| Version control (git) | ✅ Native | ❌ Manual | ✅ Native | ✅ Native | ❌ Manual |
| Developer-friendly | ✅ | ❌ | ✅✅ | ✅✅ | ❌ |
| Non-technical editors | ✅✅ | ✅✅ | ❌ | ❌ | ✅✅ |
| Self-hosted | ✅ | ❌ | ✅✅ | ✅✅ | ✅ |
| Advanced search | ✅ | ✅ | ✅ (plugin) | ✅ (plugin) | ❌ |
| API / integrations | ✅ | ✅ | ✅ (open source) | ✅ (open source) | ✅ |
| Cost (low) | ❌ (paid) | ❌ (paid) | ✅ (free) | ✅ (free) | ❌ (expensive) |
| Mobile app | ✅ | ✅ | ❌ | ❌ | ✅ |
Docusaurus (recommended for developer docs):
# Quick start
npx create-docusaurus@latest my-docs classic
cd my-docs
# Add search (Algolia DocSearch)
npm install --save @docusaurus/plugin-search-algolia
# Add versioning
npm run docusaurus docs:version 1.0.0
# Build and deploy
npm run build
# Deploy `build/` to any static host
// docusaurus.config.js
module.exports = {
title: 'My Project Docs',
tagline: 'Everything you need to build with My Project',
url: 'https://docs.myproject.com',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
presets: [
[
'classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/myorg/myproject/edit/main/docs/',
showLastUpdateTime: true,
showLastUpdateAuthor: true,
},
blog: {
showReadingTime: true,
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
},
],
],
themeConfig: {
navbar: {
title: 'My Project',
items: [
{
type: 'doc',
docId: 'intro',
position: 'left',
label: 'Docs',
},
{
type: 'docsVersionDropdown',
position: 'right',
},
{
href: 'https://github.com/myorg/myproject',
label: 'GitHub',
position: 'right',
},
],
},
algolia: {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
indexName: 'my-project',
},
},
};
MkDocs with Material theme:
# Install
pip install mkdocs mkdocs-material
# Create new project
mkdocs new .
# Serve locally
mkdocs serve
# Build
mkdocs build
# mkdocs.yml
site_name: My Project Docs
site_url: https://docs.myproject.com
theme:
name: material
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- search.highlight
- content.code.copy
- content.tabs.link
plugins:
- search
- tags
- git-revision-date-localized
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- tables
- toc:
permalink: true
nav:
- Home: index.md
- Getting Started: getting-started.md
- Guides:
- guides/index.md
- Configuration: guides/configuration.md
- Deployment: guides/deployment.md
- Reference:
- reference/index.md
- CLI: reference/cli.md
- API: reference/api.md
- Troubleshooting: troubleshooting.md
┌─────────────┐
│ Home/Landing │
│ (Overview) │
└──────┬──────┘
┌───────────────┼───────────────┐
│ │ │
┌──────┴──────┐ ┌─────┴──────┐ ┌──────┴──────┐
│ Getting │ │ Guides & │ │ Reference │
│ Started │ │ Tutorials │ │ & API Docs │
└──────┬──────┘ └─────┬──────┘ └──────┬──────┘
│ │ │
┌──────┴──────┐ ┌─────┴──────┐ ┌──────┴──────┐
│ Quick Start │ │ How-to │ │ Config │
│ Setup Guide │ │ Best │ │ CLI Ref │
│ First Steps │ │ Practices │ │ Changelog │
└─────────────┘ └────────────┘ └─────────────┘
docs/
├── index.md # Landing page
├── getting-started/
│ ├── index.md # Overview
│ ├── installation.md # Setup instructions
│ ├── quick-start.md # 5-minute tutorial
│ └── first-project.md # Guided walkthrough
├── guides/
│ ├── index.md # Guide overview
│ ├── configuration/
│ │ ├── environment.md
│ │ ├── authentication.md
│ │ └── integrations.md
│ ├── deployment/
│ │ ├── production.md
│ │ ├── staging.md
│ │ └── monitoring.md
│ └── best-practices/
│ ├── security.md
│ ├── performance.md
│ └── scalability.md
├── reference/
│ ├── index.md # Reference overview
│ ├── api.md # API documentation
│ ├── cli.md # CLI commands
│ ├── configuration.md # All config options
│ └── troubleshooting.md # Common issues & solutions
├── tutorials/
│ ├── index.md
│ ├── beginner-tutorial.md
│ └── advanced-tutorial.md
├── contributing.md # How to contribute to the KB
└── faq.md # Frequently asked questions
---
title: How to [Task Name]
description: Step-by-step guide for completing [task]
sidebar_position: 2
tags: [configuration, deployment, production]
---
# How to [Task Name]
> **Purpose**: [One-line description of what this accomplishes]
> **Prerequisites**: [List of prerequisites or links to them]
> **Estimated time**: [X minutes]
## Step 1: [First Step]
[Description of what to do]
```bash
[Command to run]
Expected result: [What should happen after this step]
[Description]
[How to confirm success]
| Problem | Solution |
|---|---|
| [Problem description] | [Solution steps] |
---
### Taxonomy and Tagging
#### Tag Taxonomy Design
```yaml
# Tag taxonomy for a developer knowledge base
#
# Category-based tags follow this hierarchy:
# domain > area > topic
tags:
# By topic area
- backend
- frontend
- infrastructure
- security
- data
- mobile
# By content type
- tutorial
- guide
- reference
- troubleshooting
- faq
# By audience
- beginner
- intermediate
- advanced
- administrator
# By system/component
- authentication
- database
- deployment
- monitoring
- api
- cli
# By project/team
- team-alpha
- team-beta
- platform
## Tagging Guidelines
### Rules
1. **Every page needs at least 2 tags**: one content type + one topic
2. **Max 5 tags per page**: too many tags dilute search
3. **Use existing tags**: check existing tags before creating new ones
4. **Keep tags lowercase**: consistent casing improves search
5. **Use nouns, not verbs**: `deployment` not `deploying`
### Tag Combinations
| Page Type | Required Tags | Recommended Tags |
|-----------|--------------|------------------|
| Getting started guide | `tutorial`, `beginner` | `setup`, `first-steps` |
| API reference | `reference`, `api` | `backend`, `integration` |
| Troubleshooting guide | `troubleshooting` | Component-related tags |
| Best practices | `guide`, `best-practices` | Domain-specific tags |
# Example: suggest tags based on page content
def suggest_tags(content: str, existing_tags: list) -> list:
"""
Suggest relevant tags based on page content analysis.
"""
keywords = {
"install": ["getting-started", "setup"],
"config": ["configuration", "setup"],
"deploy": ["deployment", "devops"],
"error": ["troubleshooting", "errors"],
"api": ["api", "integration"],
"security": ["security", "authentication"],
"database": ["database", "data"],
"monitor": ["monitoring", "observability"],
}
suggestions = set()
content_lower = content.lower()
for keyword, tags in keywords.items():
if keyword in content_lower:
suggestions.update(tags)
# Limit to most relevant
return list(suggestions)[:3]
## Writing for Search Discovery
### 1. Start with the Question
Use the question as the title so it matches what users search for:
✅ "How do I reset my password?"
✅ "Why is my deployment failing with error 503?"
❌ "Password Reset Procedure"
❌ "Deployment Error Analysis"
### 2. Include Synonyms in the First Paragraph
Users search with different vocabulary:
> "If your login fails or you can't sign in to the dashboard,
> you may need to reset your password. This guide covers
> password recovery, credential reset, and account access
> restoration."
### 3. Use Descriptive Headings
Headings are heavily weighted in search:
✅ "### Resolving Database Connection Timeouts"
❌ "### Issue Resolution"
### 4. Add a Summary Block
```markdown
> **TL;DR**: If you see "Error 503 Service Unavailable" during
> deployment, your application server is overloaded. Scale up
> your instance or check for memory leaks before redeploying.
#### Search Configuration
```yaml
# MkDocs Material search configuration
plugins:
- search:
lang:
- en
separator: '[\s\-_]'
min_search_length: 3
prebuild_index: true # Offline search support
# Docusaurus search (Algolia)
themeConfig:
algolia:
appId: YOUR_APP_ID
apiKey: YOUR_API_KEY
indexName: your-docs
contextualSearch: true
searchParameters:
hitsPerPage: 10
attributesToSnippet:
- 'title:30'
- 'content:200'
## Content Health Metrics
Track these monthly:
| Metric | Target | How to Measure |
|--------|--------|---------------|
| Stale pages (>6 months since update) | <10% | Git log / last modified dates |
| Orphaned pages (no inbound links) | <5% | Backlink analysis |
| Search failure rate | <15% | Search analytics |
| Pages with no tags | <2% | Tag metadata audit |
| Reader satisfaction | >4/5 | Feedback widget |
| Pages per contributor (monthly) | >2 | Contribution tracking |
# GitHub Action: Find stale docs
name: Stale Content Check
on:
schedule:
- cron: '0 6 1 * *' # First day of every month
jobs:
stale-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Find stale pages
run: |
echo "## Stale Documentation (not updated in 6 months)" > stale-report.md
echo "" >> stale-report.md
for file in $(find docs -name "*.md" -type f); do
last_commit=$(git log -1 --format="%cd" --date=short -- "$file")
if [[ $(date -d "$last_commit" +%s) -lt $(date -d "6 months ago" +%s) ]]; then
echo "- [$file]($file) — last updated $last_commit" >> stale-report.md
fi
done
- name: Create Issue
uses: actions/github-script@v6
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('stale-report.md', 'utf8');
await github.rest.issues.create({
owner: context.repo.owner,
repo: context.repo.repo,
title: 'Monthly Stale Content Report',
body: body,
labels: ['documentation', 'maintenance']
});
┌─────────────┐
│ DRAFT │ ← Created by contributor
└──────┬──────┘
│
┌──────┴──────┐
│ REVIEW │ ← Peer/SME review
└──────┬──────┘
│
┌──────┴──────┐
│ PUBLISHED │ ← Live in knowledge base
└──────┬──────┘
│
┌─────────┴─────────┐
│ │
┌──────┴──────┐ ┌──────┴──────┐
│ UPDATED │ │ ARCHIVED │
└──────┬──────┘ └─────────────┘
│
┌──────┴──────┐
│ REMOVED │
└─────────────┘
## Cross-Referencing Best Practices
### Types of References
**Related guides**: Links to other how-to guides on related topics
> See also: [How to Configure Authentication](./authentication.md)
**Prerequisites**: Links to content users need before starting
> **Prerequisites**: [Installation Guide](./installation.md), [Account Setup](./account-setup.md)
**Deeper dives**: Links from overviews to detailed content
> For more detail, see [API Reference](../reference/api.md)
**Troubleshooting links**: Connect error messages to solutions
> If you see "Error 403: Forbidden", see [Troubleshooting Access Issues](./troubleshooting.md#403)
### Implementation
```markdown
## Resetting a User Password
> **Prerequisites**:
> - [Admin access setup](./admin-access.md)
> - User's email address or user ID
1. Log into the [Admin Dashboard](https://admin.example.com)
2. Navigate to **Users > Search**
3. Find the user and click **Reset Password**
4. The system sends a password reset email
> **Related**: [Bulk User Management](./bulk-user-management.md) |
> [Troubleshooting: Reset email not received](./troubleshooting.md#reset-email)
---
### Contribution Workflows
#### CONTRIBUTING.md for Knowledge Base
```markdown
# Contributing to the Knowledge Base
We welcome contributions from everyone. Here's how to add or improve content.
## Quick Start
1. Fork the knowledge base repository
2. Create a branch: `git checkout -b docs/my-new-guide`
3. Write your content in Markdown
4. Submit a Pull Request
## Content Standards
- **Title**: Clear, question-based or task-based title
- **Description**: One-line summary in frontmatter
- **Tags**: At least 2 tags (content type + topic)
- **Structure**: Prerequisites → Steps → Verification → Troubleshooting
- **Examples**: Include at least one runnable command or code snippet
## Templates
Use the template at `docs/_templates/guide.md` for new guides.
## Review Process
1. **Automated checks**: Markdown linting, link checking, spell check
2. **Peer review**: At least one team member reviews for accuracy
3. **Editorial review**: Content style and structure check (for major additions)
4. **Merge**: Squash and merge to main
## What Gets Accepted
| Type | Accepted? | Review Level |
|------|-----------|-------------|
| New guide | ✅ Yes | Full review |
| Typos/corrections | ✅ Yes | Quick review |
| Code example updates | ✅ Yes | SME review |
| Major rewrites | ✅ Yes | Full review |
| Duplicate content | ❌ No | — |
| Personal opinions | ❌ No | — |
| Outdated information | ⚠️ Requires update | Full review |
## Contributor Dashboard
| Month | Contributors | New Pages | Updates | Top Contributor |
|-------|-------------|-----------|---------|-----------------|
| Jan 2024 | 12 | 8 | 34 | @alice |
| Feb 2024 | 15 | 6 | 42 | @bob |
| Mar 2024 | 18 | 11 | 55 | @carol |
<!-- Add to every page -->
## Was this page helpful?
- [✅ Yes] [❌ No]
<!-- If No -->
**What could we improve?**
[Free text field]
<!-- Footer -->
Last updated: {{ git_revision_date }}
[Edit this page]({{ edit_url }})
// Docusaurus analytics integration
// docusaurus.config.js
module.exports = {
themeConfig: {
// Plausible (privacy-focused analytics)
plausible: {
domain: 'docs.myproject.com',
},
// Or Google Analytics
googleAnalytics: {
trackingID: 'UA-XXXXX-Y',
anonymizeIP: true,
},
},
};
| Metric | What It Tells You | Action When Low |
|---|---|---|
| Search success rate | Are people finding what they need? | Improve content, tags, search config |
| Page views per article | Which content is most/least used? | Promote popular, fix or archive unpopular |
| Time on page | Are people reading or bouncing? | Improve content quality, add examples |
| Feedback score | Are users satisfied? | Address negative feedback patterns |
| Return visits | Is the KB sticky? | Add more cross-references, update content |
| Contribution rate | Is the community engaged? | Lower barriers, celebrate contributors |
| Role | Responsibilities | Who |
|---|---|---|
| KB Owner | Overall strategy, roadmap, metrics | PM or Tech Lead |
| Content Stewards | Content quality, templates, style guide | Tech Writer |
| Subject Matter Experts | Technical accuracy, review, contribution | Engineers |
| Editors | Review, merge, publishing | Senior contributors |
| All Contributors | Write, update, fix content | Everyone |
# Content review cadence by type
review_schedule:
critical:
- security procedures: monthly
- incident response: monthly
- authentication docs: quarterly
standard:
- guides and tutorials: quarterly
- api reference: with each release
- faq: semi-annually
minor:
- internal procedures: annually
- project overviews: annually
Building without a search strategy: A knowledge base with poor search is a graveyard. Invest in search from day one.
No content owners: Pages without an owner go stale. Every page should have a clearly documented owner.
Too many platforms: Don't split knowledge across Notion, Confluence, and a wiki. Pick one and migrate everything.
Over-organizing: Creating too many categories and subcategories buries content. Flat structures with good tags outperform deep hierarchies.
Perfectionism over publishing: Docs that are 80% complete and published are infinitely better than perfect docs that never ship.
Not tagging content: A well-tagged page is discoverable. An untagged page is lost. Enforce tagging in your workflow.
Ignoring stale content: Outdated documentation actively harms trust. Implement automated stale content detection.
No contribution guidelines: If people don't know how to contribute, they won't. Make it trivially easy.
No feedback loop: Without user feedback, you're writing in the dark. Add a "Was this helpful?" widget on every page.
Treating the KB as a side project: Allocate dedicated time for KB maintenance, or it will decay into an abandoned graveyard.
| Criterion | 1 - Graveyard | 2 - Collection | 3 - Organized | 4 - Curated | 5 - Living |
|---|---|---|---|---|---|
| Platform | No platform | Basic wiki | Purpose-built KB | Optimized KB | Integrated ecosystem |
| Structure | No structure | Basic folders | Taxonomy defined | Information architecture | Adaptive, user-validated IA |
| Search | None | Text search | Tagged + text search | Faceted search | AI-assisted semantic search |
| Content Freshness | Never updated | Updated reactively | Scheduled reviews | Automated stale detection | Continuous improvement |
| Contribution | No process | A few contributors | Defined workflow | Contributor program | Embedded in daily workflow |
| Governance | No ownership | Unclear ownership | Defined roles | Editorial board | Metrics-driven governance |
| Feedback | None | Occasional | Feedback widget | Analytics-driven | Predictive content recommendations |