68 lines
3.0 KiB
Markdown
68 lines
3.0 KiB
Markdown
---
|
|
type: user-guide
|
|
title: [Human-readable title]
|
|
summary: [1-2 sentences answering "what mental model + gotchas does using [tool] well require?" — NOT what the tool does or a feature list]
|
|
tags:
|
|
- type/user-guide
|
|
- tool/[tool]
|
|
- domain/[field] # if applicable
|
|
- client/[client] # if client-specific
|
|
- project/[project] # if project-specific
|
|
scope: [global|project|client]
|
|
last_updated: YYYY-MM-DD
|
|
date: YYYY-MM-DD # creation date — set once, never updated
|
|
update_note: experience-driven # keep — user guides update when a session finds a new gotcha or a discrepancy
|
|
related:
|
|
- [note-slug] # cross-links to companion notes; omit if none
|
|
source: [project name] # project that spawned the note
|
|
---
|
|
|
|
# [Tool Name] — User Guide
|
|
|
|
<!-- REMINDER before you fill this: this is NOT a how-to. No numbered steps. Command
|
|
syntax gets the compact table in "Command Reference" at most — everything else
|
|
is nuance: semantics, distinctions, gotchas, judgment calls a competent user has
|
|
internalized. If a section would just restate --help output, cut it. -->
|
|
|
|
## What it is
|
|
<!-- One paragraph. What the tool does and the one-sentence mental model of its purpose —
|
|
enough for the reader to recognize "this is/isn't the tool for my situation." Do NOT
|
|
restate the summary; do NOT give a feature list. -->
|
|
|
|
## Mental model
|
|
<!-- The key concepts and distinctions the reader must hold to reason about the tool
|
|
correctly — the vocabulary and the boundaries between modes/concepts that command
|
|
syntax alone does not convey (e.g. "X vs Y look similar but differ in Z"). This is
|
|
what makes the rest of the guide (and the tool's own docs) parseable. -->
|
|
|
|
## Nuances & gotchas
|
|
<!-- The meat of the guide — the heaviest section. Each item: the surprising behavior,
|
|
why it exists (if known), and how to recognize/avoid/recover from it. Prioritize
|
|
things that look safe but aren't, defaults that surprise, or state that silently
|
|
changes behavior. One sub-heading or bullet per nuance; don't pad with obvious facts. -->
|
|
|
|
## When NOT to use it / limits
|
|
<!-- The boundary: situations where this tool is the wrong choice, or where it stops
|
|
working as expected. Prevents the reader from forcing a bad fit. Omit only if the
|
|
tool genuinely has no such boundary (rare — justify the omission to yourself first). -->
|
|
|
|
## Command reference
|
|
<!-- Compact table ONLY — command/flag → one-line effect. No walkthroughs, no examples
|
|
of full sessions. If there's nothing beyond what --help already says clearly, cut
|
|
this section entirely rather than restate --help. -->
|
|
|
|
| Command | Effect |
|
|
|---|---|
|
|
| `[command]` | [one-line effect] |
|
|
|
|
## Pointers
|
|
<!-- Where to go deeper: repo paths, ADRs, specs, upstream docs. One line each — what
|
|
the reader finds there, not a restatement of its content. -->
|
|
|
|
- [path/to/repo] — [what's there]
|
|
|
|
## Related
|
|
<!-- Wikilinks to companion notes, one line each on why it is relevant. -->
|
|
|
|
- [[note-slug]] — why it is relevant
|