docs: split the README from the full reference before v0.1.0 #10

New issue

Closed

opened 2026-04-25 16:16:54 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-25 16:16:54 +00:00

The README has crossed from landing page into manual.

That is not automatically wrong for a tmux plugin, but it is wrong here:

the runtime surface is still fairly small
the plugin ships no default keybindings
TPM, manual, and nix installation all matter and should stay easy to find
algorithm-specific behavior matters, but it does not belong in the first screenful of the repo front page
the current single-file structure makes the important parts hard to scan and hard to trust

Research notes:

suckless-style docs bias toward a short front page with clear scope, constraints, and deeper material split out
established tmux plugins often keep the README focused and move advanced setup/troubleshooting/reference material into docs/
bigger tiling plugins do keep a full-manual README, but they also own a much larger command/keybinding surface than mosaic does

This issue is no longer a copy pass. It is a docs structure pass.

Goals

make the README fast to scan for someone who already knows tmux
keep installation obvious for TPM, manual, and nix users
document the real user-facing surface precisely
make per-algorithm behavior easy to find without forcing everyone through a giant README
remove or shrink sections that only exist because the structure is wrong

Plan

rewrite README as a landing page: what it is, why it exists, quickstart, core options/ops, limits
state explicitly that mosaic installs no default keybindings; any bindings shown are examples only
move installation detail into dedicated docs so TPM/manual/nix setup can stay complete without bloating README
move algorithm reference out of README into dedicated docs
document each algorithm's behavior, supported operations, relevant options, and example usage
decide whether algorithm docs read better as one reference page with anchors or one file per algorithm
remove the FAQ unless real recurring questions remain after the rewrite
keep hard constraints under limitations, not FAQ
verify every snippet and option name against the implementation/tests

Success here is not "shortest possible README". It is a README that acts like a landing page instead of a scrollback dump, with the rest of the reference material moved somewhere that is easier to navigate.

The README has crossed from landing page into manual. That is not automatically wrong for a tmux plugin, but it is wrong here: - the runtime surface is still fairly small - the plugin ships no default keybindings - TPM, manual, and nix installation all matter and should stay easy to find - algorithm-specific behavior matters, but it does not belong in the first screenful of the repo front page - the current single-file structure makes the important parts hard to scan and hard to trust Research notes: - suckless-style docs bias toward a short front page with clear scope, constraints, and deeper material split out - established tmux plugins often keep the README focused and move advanced setup/troubleshooting/reference material into docs/ - bigger tiling plugins do keep a full-manual README, but they also own a much larger command/keybinding surface than mosaic does This issue is no longer a copy pass. It is a docs structure pass. ## Goals - make the README fast to scan for someone who already knows tmux - keep installation obvious for TPM, manual, and nix users - document the real user-facing surface precisely - make per-algorithm behavior easy to find without forcing everyone through a giant README - remove or shrink sections that only exist because the structure is wrong ## Plan - [ ] rewrite README as a landing page: what it is, why it exists, quickstart, core options/ops, limits - [ ] state explicitly that mosaic installs no default keybindings; any bindings shown are examples only - [ ] move installation detail into dedicated docs so TPM/manual/nix setup can stay complete without bloating README - [ ] move algorithm reference out of README into dedicated docs - [ ] document each algorithm's behavior, supported operations, relevant options, and example usage - [ ] decide whether algorithm docs read better as one reference page with anchors or one file per algorithm - [ ] remove the FAQ unless real recurring questions remain after the rewrite - [ ] keep hard constraints under limitations, not FAQ - [ ] verify every snippet and option name against the implementation/tests Success here is not "shortest possible README". It is a README that acts like a landing page instead of a scrollback dump, with the rest of the reference material moved somewhere that is easier to navigate.