npl-update-howto-docs

PROJ-HOWTO.md — Maintenance Guide

Purpose

docs/PROJ-HOWTO.md provides task-oriented guides for the things a user will actually need to do with this project or component. Where PROJ-ARCH explains what it is and PROJ-LAYOUT where things live, HOWTO answers "how do I…?" for the likely tasks — with runnable steps.

Structure

docs/
├── PROJ-HOWTO.md         # Index + short guides (keep small)
├── PROJ-HOWTO.summary.md # Companion: task list + one-line outcomes
└── howto/
    ├── first-hour.md     # Extracted long guides, one task each
    ├── produce-rich-formats.md
    └── ...

Selecting Tasks to Document

Prioritize, in order:

1. First-hour tasks — install, configure, verify it works
2. The recurring workflow — the 2-5 things users do weekly with this tool
3. Non-obvious capability — powerful features hidden behind flags/config a user wouldn't guess (e.g. using tabbing-on to track what you worked on over time; using media-tool to produce syntactically rich, correct output in niche or post-training-cutoff file formats)
4. Sharp edges — tasks where the naive approach fails and the correct path needs stating

Skip tasks that are self-evident from --help unless the flags interact in surprising ways.

Guide Format

Each guide follows this template:

## How to: [task in the user's words]

**Goal:** [one sentence — the outcome, not the mechanism]
**Prereqs:** [installed tools, env vars, access needed — link, don't re-explain]

1. [Step with the exact command in a code block]
2. [Step]

**Verify:** [command or observation proving it worked]
**Gotchas:** [the 1-3 ways this commonly fails, each with the fix]

Rules

• Commands must be copy-paste runnable against the current code — test or trace each one during the update
• Lead with the common case; variants go under Gotchas or a short "Variations" note
• Link to PROJ-ARCH/PROJ-FAQ for why; HOWTO stays on how
• Use the user's vocabulary in headings ("How to: track what I worked on this week"), not internal module names