Skip to content

User Documentation Structure

Purpose

Defines the organization and structure of user-facing documentation in AudioLab. This ensures consistency, discoverability, and maintainability of documentation content.

Directory Layout

10_DOCUMENTATION/
└── user_guide/
    ├── index.md                    # Homepage
    ├── getting-started/            # New user onboarding
    │   ├── introduction.md
    │   ├── installation.md
    │   ├── quick-start.md
    │   └── first-plugin.md
    ├── user-guide/                 # Comprehensive guides
    │   ├── overview.md
    │   ├── core-concepts.md
    │   ├── audio-processing.md
    │   ├── parameters.md
    │   ├── events.md
    │   ├── state-management.md
    │   └── lifecycle.md
    ├── tutorials/                  # Step-by-step tutorials
    │   ├── basic-effects.md
    │   ├── advanced-dsp.md
    │   ├── realtime-safety.md
    │   ├── simd.md
    │   └── testing.md
    ├── reference/                  # Technical reference
    │   ├── api.md
    │   ├── architecture.md
    │   ├── performance.md
    │   └── platforms.md
    ├── best-practices/             # Guidelines and patterns
    │   ├── code-style.md
    │   ├── documentation.md
    │   ├── testing.md
    │   └── performance.md
    ├── faq.md                      # Frequently asked questions
    ├── glossary.md                 # Term definitions
    ├── contributing.md             # Contribution guide
    └── changelog.md                # Version history

Content Categories

1. Getting Started (New Users)

Audience: Developers new to AudioLab Goal: Get from zero to working plugin in <30 minutes Style: Tutorial-like, step-by-step, beginner-friendly

Topics: - Introduction to AudioLab - Installation guide (Windows, macOS, Linux) - Quick start guide (hello world plugin) - First real plugin (simple gain effect)

Requirements: - All commands must be copy-paste ready - Include expected output/results - Provide troubleshooting for common issues - Link to next steps

2. User Guide (Core Documentation)

Audience: Active AudioLab users Goal: Comprehensive understanding of framework features Style: Explanatory, conceptual, with practical examples

Topics: - Framework overview and architecture - Core concepts (buffers, sample types, etc.) - Audio processing pipeline - Parameter system and automation - Event system and messaging - State management and serialization - Plugin lifecycle management

Requirements: - Explain WHY, not just HOW - Include diagrams for complex concepts - Provide code examples for each feature - Link to API reference

3. Tutorials (Hands-On Learning)

Audience: Users learning specific techniques Goal: Build real plugins while learning Style: Step-by-step, project-based

Topics: - Building basic effects (gain, filter, delay) - Advanced DSP techniques (FFT, convolution) - Real-time safety patterns - SIMD optimization techniques - Testing strategies (unit, integration, quality)

Requirements: - Complete working code provided - Explain each step in detail - Show common mistakes and how to avoid them - Include exercises/challenges

4. Reference (Technical Specs)

Audience: Experienced users seeking details Goal: Quick lookup of technical information Style: Concise, technical, comprehensive

Topics: - API reference (link to Doxygen) - System architecture - Performance characteristics - Platform-specific details

Requirements: - Tables for quick scanning - Link to source code - Version compatibility notes - Performance benchmarks

5. Best Practices (Guidelines)

Audience: All users Goal: Establish project standards and patterns Style: Prescriptive, with rationale

Topics: - Code style guide - Documentation standards - Testing best practices - Performance optimization guide

Requirements: - Show good vs bad examples - Explain rationale for each practice - Provide automated tooling where possible - Link to enforcement mechanisms (linters, CI)

6. Supporting Pages

Audience: Various Goal: Answer common questions and provide metadata

Topics: - FAQ - Common questions and answers - Glossary - Term definitions - Contributing - How to contribute to AudioLab - Changelog - Version history and migration guides

Content Requirements

Every Page Must Have

  1. Front Matter (Metadata) 

    ---
title: Page Title
description: Brief description for SEO
---

  2. Header Structure 

    # Page Title

Brief introduction (1-2 sentences) explaining what this page covers.

## Section 1
Content...

## Section 2
Content...

  3. Navigation Hints 

    ## Next Steps
- [Related Topic 1](../path/to/topic1.md)
- [Related Topic 2](../path/to/topic2.md)

Code Examples

All code must be: - Syntax highlighted: Use proper language markers - Complete: Runnable without modifications - Commented: Explain non-obvious parts - Tested: Code examples must compile

Example: 

```cpp
// AudioProcessor.hpp
#include <audiolab/core/AudioBuffer.hpp>

class SimpleGain {
public:
    void process(audiolab::AudioBuffer<float>& buffer, float gain) {
        // Process each channel
        for (size_t ch = 0; ch < buffer.getNumChannels(); ++ch) {
            float* data = buffer.getChannelData(ch);

            // Apply gain to each sample
            for (size_t i = 0; i < buffer.getNumSamples(); ++i) {
                data[i] *= gain;
            }
        }
    }
};
```

Diagrams

Use Mermaid for diagrams: 

```mermaid
graph LR
    A[Input Buffer] --> B[Process Block]
    B --> C[Output Buffer]
    D[Parameters] --> B
```

Admonitions (Callouts)

Use for notes, warnings, tips: 

!!! note "Performance Tip"
    Use SIMD intrinsics for processing large buffers (>128 samples).

!!! warning "Thread Safety"
    This function is NOT thread-safe. Use external locking.

!!! example "Example"
    See `examples/basic_gain.cpp` for a complete implementation.

Writing Style Guide

Voice and Tone

  • Active voice: "Call process()" not "The process method should be called"
  • Second person: "You can use..." not "One can use..."
  • Present tense: "This function returns..." not "will return"
  • Professional but friendly: Avoid jargon, explain technical terms

Structure

  • Progressive disclosure: Simple explanation first, details later
  • Chunking: Break long content into sections with headers
  • Lists: Use lists for 3+ items
  • Tables: Use for structured data comparison

Code Comments

// ✅ GOOD - Explains WHY
// Pre-multiply by 0.5 to avoid range check in inner loop
float halfGain = gain * 0.5f;

// ❌ BAD - Explains WHAT (obvious from code)
// Multiply gain by 0.5
float halfGain = gain * 0.5f;

Common Mistakes to Avoid

❌ Too technical for beginners 

The DFT is computed via the Cooley-Tukey radix-2 decimation-in-time algorithm.

✅ Accessible explanation 

The Fast Fourier Transform (FFT) converts audio from the time domain to the
frequency domain, allowing you to analyze or modify individual frequencies.

❌ Missing context 

Call `initialize()` before processing.

✅ Full context 

Before calling `process()`, you must call `initialize()` with the sample rate
and maximum buffer size. This allocates internal buffers and prepares filters.

File Naming Conventions

  • All lowercase: getting-started.md not Getting-Started.md
  • Hyphens for spaces: quick-start.md not quick_start.md
  • Descriptive names: simd-optimization.md not simd.md
  • No abbreviations: frequently-asked-questions.md not faq.md (except for well-known acronyms)

Cross-Referencing

See the [Parameter System](../user-guide/parameters.md) for details.

See [`AudioBuffer`](../../api/html/classAudioBuffer.html) for API details.

See [`AudioProcessor.hpp`](https://github.com/audiolab/audiolab/blob/main/04_CORE/AudioProcessor.hpp)

Versioning Documentation

Version Badges

!!! info "Version Info"
    This feature was added in version 1.2.0

Deprecation Notices

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

Localization (Future)

Current: English only Future: Support for multiple languages

Placeholder structure: 

10_DOCUMENTATION/
├── en/           # English (current)
├── es/           # Spanish (future)
├── ja/           # Japanese (future)
└── zh/           # Chinese (future)

Metrics and Quality

Track These Metrics

  • Coverage: % of features documented
  • Freshness: Days since last update
  • Broken links: Number of dead links
  • User feedback: Thumbs up/down on pages

Quality Checklist

  • All code examples tested and working
  • No broken links (internal or external)
  • Diagrams up-to-date with implementation
  • Screenshots current (not outdated UI)
  • Spelling and grammar checked
  • Technical review completed

Maintenance Schedule

  • Weekly: Check for broken links
  • Monthly: Update screenshots and examples
  • Per Release: Update changelog and migration guides
  • Quarterly: Review and refresh outdated content

References