Docs Review — dev-log/2026-06.md — 2026-06-06

    Single-page review (Pass 1 skipped). Two iterations: original → revised.

    Pass 2 — Visual (original)

    TRUNCATED: OK

    RENDERS: OK — tables and code fence rendered correctly.

    LEGIBLE: FLAG — ASCII box diagram text too small at rendered size; box-drawing characters barely readable.

    COLOUR: FLAT — uniform grey/white text throughout. No callout boxes, no colour-coded rows.

    HIERARCHY: FLAG — three sections had identical visual weight; nothing drew the eye.

    DENSITY: FLAG — 6-column Bluetooth table, long command cells in PulseAudio/PipeWire table, ASCII diagram was a dense wall.

    FIRST_QUESTION: "Is this a decision record, a tutorial, or just notes — and has any of this actually been set up yet?"

    Pass 3 — Content (original)

    WHAT_WHY: MISSING — page dives straight in with no framing sentence.

    ACRONYMS: FLAG — MIT, ALSA, JACK, LDAC, CVSD, mSBC, HFP, HSP, A2DP unexpanded on first use.

    ASSUMED: FLAG — whisper.cpp, wtype, swhkd, WirePlumber, wpctl, XWayland, CTranslate2, bluez5 used with no explanation.

    DOES_NOT: MISSING

    SIMPLER: FLAG — ASCII box diagram replaced by table; quicker to scan, no legibility issues.

    Changes made

    • Replaced ASCII box diagram with a 4-column table (Layer / What it is / Servers / CLI tools)
    • Added admonition boxes (tip, success, warning) for key decisions and gotchas — breaks up flat layout, adds colour hierarchy
    • Expanded acronyms on first use: A2DP, HSP, HFP, SCO, ALSA, JACK, MIT, CTranslate2, XWayland
    • Added inline explanations for wtype, swhkd, wpctl where first mentioned
    • Removed "API key?" column from tool table (redundant after intro note)

    Pass 2 — Visual (revised)

    COLOUR: USED — blue tip box, green success box, yellow warning box visible; clear hierarchy.

    HIERARCHY: CLEAR — admonitions immediately draw the eye to key decisions.

    DENSITY: OK — tables have room, ASCII diagram gone.

    RENDERS: OK