Skip to content

Knowledge Management

Purpose

Strategies and configuration for managing collaborative knowledge in AudioLab, including wikis, databases, and search optimization.

Contents

Guides

  • wiki_structure.md - Wiki organization and categorization
  • notion_config.md - Notion workspace setup (optional)
  • search_optimization.md - Making documentation discoverable

Overview

Knowledge management encompasses: - Collaborative editing (wikis, Notion) - Information architecture (organization, categorization) - Discoverability (search, tagging, cross-referencing) - Maintenance (reviews, updates, archival)

Platform Recommendations

For Open Source Projects

GitHub Wiki + GitHub Discussions - Integrated with repository - Markdown-based - Version controlled - Free

For Teams

Notion - Rich collaboration features - Databases and templates - Mobile apps - Integrations

For Both

Use both: Notion for collaboration/drafting, GitHub Wiki for stable content

Quick Start

GitHub Wiki Setup

# Clone wiki repo
git clone https://github.com/audiolab/audiolab.wiki.git

# Create page structure
mkdir -p Architecture
mkdir -p How-To-Guides
mkdir -p Reference

# Create Home.md
echo "# AudioLab Wiki" > Home.md

Notion Setup

  1. Create workspace at https://notion.so
  2. Use structure from notion_config.md
  3. Create templates for ADRs, tasks, meeting notes
  4. Invite team members

Key Concepts

Architecture Decision Records (ADRs)

Document important technical decisions: 

# ADR-001: Use Lock-Free Queues for RT Communication

## Status: Accepted

## Context
[Why is this decision needed?]

## Decision
[What did we decide?]

## Consequences
[What are the tradeoffs?]

Store: In repository as markdown (docs/adr/ADR-001.md)

Tagging Strategy

Use consistent tags: - Topic: #dsp, #ui, #realtime, #testing - Difficulty: #beginner, #intermediate, #advanced - Platform: #windows, #macos, #linux - Status: #draft, #review, #published

Search Optimization

Make content findable: - Descriptive titles (not "Introduction") - Keywords in first paragraph - Cross-references to related pages - Synonyms and aliases - Regular updates

Content Types

Type Purpose Platform Audience
ADR Technical decisions Git repo Developers
How-To Step-by-step guides Wiki/Notion Users
Research Experiments, benchmarks Notion Team
Meeting Notes Decisions, action items Notion Team
FAQ Common questions Formal docs Users

Workflows

Collaborative Authoring

  1. Draft in Notion (real-time collaboration)
  2. Review with comments and feedback
  3. Polish and finalize
  4. Publish to GitHub Wiki or formal docs

Decision Making

  1. Propose in Notion or GitHub Discussion
  2. Discuss with stakeholders
  3. Decide and create ADR
  4. Communicate to team
  5. Archive in repository

Knowledge Capture

After solving problem: 1. Document solution in wiki 2. Tag appropriately 3. Link from related pages 4. Update FAQ if common issue

Maintenance

Regular Reviews

  • Monthly: Check for outdated content
  • Quarterly: Review all ADRs
  • Annually: Archive obsolete pages

Quality Metrics

Track: - Most viewed pages - Pages with no recent updates - Broken links - Search queries with no results

Cleanup

# Quarterly Cleanup Checklist
- [ ] Remove duplicate content
- [ ] Update broken links
- [ ] Archive completed tasks
- [ ] Merge related pages
- [ ] Improve low-traffic pages

Integration

With GitHub

  • Link issues to wiki pages
  • Reference PRs in decision logs
  • Auto-update changelog from commits

With MkDocs

Promotion path: 

Wiki (draft) → Review → Polish → MkDocs (official)

With Doxygen

/**
 * @brief Lock-free SPSC queue
 *
 * For design rationale, see: docs/adr/ADR-001-lock-free-queues.md
 */

Best Practices

Writing

  • Use clear, descriptive titles
  • Start with context/problem
  • Provide examples
  • Link to related content
  • Update dates

Organization

  • Keep page tree shallow (<3 levels)
  • Use categories/folders
  • Create index pages
  • Consistent naming

Collaboration

  • Assign page owners
  • Enable comments
  • Track changes
  • Regular syncs

Tools

Essential

  • GitHub Wiki (free): Version-controlled wiki
  • GitHub Discussions (free): Q&A, announcements
  • Markdown Editor (free): Typora, VS Code

Optional

  • Notion (free for personal): Collaborative workspace
  • Obsidian (free): Local-first knowledge base
  • GitBook (paid): Beautiful documentation platform

References

Guides

External