Skip to content

Wiki Structure and Organization

Purpose

Defines structure for collaborative knowledge management in AudioLab, including wiki organization, categorization, and tagging strategies.

Wiki Platform Options

  • Pros: Integrated with repo, markdown-based, version controlled
  • Cons: Limited features, basic search
  • Best for: Technical documentation, API notes, architecture decisions
  • Pros: Rich formatting, databases, collaboration
  • Cons: Not open source, requires account
  • Best for: Project management, brainstorming, meeting notes

GitBook

  • Pros: Beautiful UI, good search, versioning
  • Cons: Paid for private repos
  • Best for: Product documentation, user guides

Confluence

  • Pros: Enterprise features, integrations
  • Cons: Expensive, complex
  • Best for: Large organizations

Information Architecture

Top-Level Categories

AudioLab Wiki
├── 📚 Getting Started
│   ├── New Contributor Onboarding
│   ├── Development Environment Setup
│   └── First Contribution Guide
│
├── 🏗️ Architecture
│   ├── System Overview
│   ├── Module Design Documents
│   ├── API Design Decisions
│   └── Performance Architecture
│
├── 💡 How-To Guides
│   ├── Building Plugins
│   ├── Testing Strategies
│   ├── Debugging Techniques
│   └── Optimization Tips
│
├── 📖 Reference
│   ├── Coding Standards
│   ├── Build System Reference
│   ├── Platform-Specific Notes
│   └── Dependency Management
│
├── 🔬 Research & Experiments
│   ├── DSP Algorithm Research
│   ├── Performance Benchmarks
│   ├── Proof of Concepts
│   └── Alternative Approaches
│
├── 🗂️ Project Management
│   ├── Roadmap
│   ├── Release Planning
│   ├── Meeting Notes
│   └── Decision Log (ADRs)
│
└── ❓ FAQ & Troubleshooting
    ├── Common Issues
    ├── Platform-Specific Problems
    ├── Build Errors
    └── Runtime Debugging

Page Templates

Architecture Decision Record (ADR)

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

## Status
Accepted

## Context
Real-time audio threads cannot block. Traditional mutexes can cause priority
inversion and audio dropouts.

## Decision
Use single-producer, single-consumer (SPSC) lock-free queues for parameter
updates from UI to audio thread.

## Consequences
### Positive
- Guaranteed real-time safety
- No priority inversion
- Predictable worst-case latency

### Negative
- Limited to SPSC pattern
- More complex implementation
- Requires understanding of memory ordering

## Alternatives Considered
- Mutexes with try_lock (rejected: still can fail)
- Atomic variables (rejected: limited data types)
- Lock-free MPMC queue (rejected: overkill for our use case)

## References
- Herb Sutter: Lock-Free Programming
- https://github.com/cameron314/readerwriterqueue

How-To Guide Template

# How to Implement a Custom Effect

## Prerequisites
- AudioLab SDK installed
- C++17 compiler
- Basic DSP knowledge

## Overview
This guide shows how to create a custom audio effect processor.

## Steps

### 1. Create Effect Class
[Detailed instructions]

### 2. Implement Process Method
[Code example]

### 3. Add Parameters
[Parameter setup]

### 4. Register with Plugin
[Registration code]

## Testing
[How to test the effect]

## Troubleshooting
- **Issue:** Effect causes audio glitches
  - **Solution:** Check for allocations in process()

## See Also
- [API Reference](link)
- [Example Effects](link)

Research Note Template

# Research: Fast Approximation for exp()

## Summary
Evaluating fast exponential approximations for use in envelope generators.

## Goal
Replace std::exp() with faster approximation while maintaining <0.1% error.

## Methods Tested
1. Polynomial approximation (Remez)
2. Lookup table with interpolation
3. SSE2 intrinsics

## Results
| Method | Speed | Max Error | Notes |
|--------|-------|-----------|-------|
| std::exp() | 1.0x | N/A | Baseline |
| Polynomial | 3.2x | 0.08% | Best accuracy |
| LUT | 5.1x | 0.15% | Fast but imprecise |
| SSE2 | 4.8x | 0.05% | **Recommended** |

## Implementation
[Code snippets]

## Conclusion
SSE2 intrinsics provide best balance of speed (4.8x) and accuracy (0.05%).
Use polynomial fallback for non-SSE platforms.

## References
- https://github.com/ekmett/approximate
- Remez Exchange Algorithm paper

Tagging Strategy

Tag Categories

By Topic

  • #dsp - Digital signal processing
  • #ui - User interface
  • #realtime - Real-time safety
  • #performance - Optimization
  • #testing - Testing strategies
  • #build - Build system

By Difficulty

  • #beginner - New contributors
  • #intermediate - Some experience
  • #advanced - Expert level

By Platform

  • #windows - Windows-specific
  • #macos - macOS-specific
  • #linux - Linux-specific
  • #cross-platform - All platforms

By Status

  • #draft - Work in progress
  • #review - Needs review
  • #published - Finalized
  • #outdated - Needs update

Tagging Example

---
title: Implementing SIMD Filters
tags: [dsp, performance, advanced, cross-platform]
status: published
author: AudioLab Team
date: 2025-01-15
---

Search Optimization

Make Content Findable

Use Descriptive Titles

✅ "How to Debug RT Audio Glitches on Windows"
❌ "Debugging"

Add Aliases/Synonyms

---
title: Parameter Smoothing
aliases: [parameter interpolation, value ramping]
---

Include Common Misspellings

**Q: Why is my paramater not updating?** (Note: parameter)
A: Check that you're calling notifyParameterChanged()...

Cross-Reference

## See Also
- [Real-Time Safety Guide](../realtime-safety.md)
- [Lock-Free Queues](../architecture/lock-free-queues.md)
- [Parameter System API](../api/parameters.md)

Collaborative Features

Page Ownership

Assign maintainers to key pages: 

---
maintainers: [@user1, @user2]
last_review: 2025-01-15
next_review: 2025-04-15  # Quarterly review
---

Discussion/Comments

Enable discussions on wiki pages (GitHub Discussions, Notion comments)

Change Notifications

  • Watch pages for changes
  • Subscribe to category updates
  • Weekly digest emails

Versioning Strategy

Version-Specific Pages

For breaking changes, create versioned pages: 

API-Reference-v1.md
API-Reference-v2.md  (current)

Migration Guides

When API changes: 

# Migrating from v1 to v2

## Breaking Changes
- `AudioBuffer::getData()` → `AudioBuffer::getChannelData()`
- `Parameter::set()` → `Parameter::setValue()`

## Code Examples
### Before (v1)
[old code]

### After (v2)
[new code]

Deprecation Notices

!!! warning "Deprecated in v2.0"
    This API is deprecated. Use `NewAPI` instead.
    Removal planned for v3.0.

Maintenance

Regular Reviews

  • Monthly: Check "needs update" pages
  • Quarterly: Review all architecture decisions
  • Annually: Archive obsolete content

Quality Metrics

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

Cleanup Tasks

# Cleanup Checklist
- [ ] Remove duplicate content
- [ ] Update broken links
- [ ] Archive outdated pages
- [ ] Improve low-traffic pages or remove
- [ ] Standardize formatting

Integration with Documentation

Wiki vs. Formal Docs

Use Wiki For: - Informal how-tos and tips - Brainstorming and drafts - Meeting notes and decisions - Experimental ideas

Use Formal Docs For: - Official API reference - User-facing tutorials - Release notes - Stable, reviewed content

Promotion Path

Wiki Draft → Review → Polish → Formal Documentation

Example workflow: 1. Write initial how-to in wiki 2. Get feedback from community 3. Refine and add examples 4. Promote to official MkDocs tutorial

References