technical-writing

Files (1)

• SKILL.md

SKILL.md (first lines)

# technical-writing

Patterns for clear technical writing in documentation, READMEs, API references, and design documents.

## Clarity

One idea per sentence. One topic per paragraph.
- Use simple subject-verb-object order. Avoid nested clauses.
- Replace jargon with plain language unless the term is standard for the audience.
- Define acronyms on first use. Do not assume the reader knows internal project names.
- Use active voice: "The scheduler retries failed tasks" not "Failed tasks are retried by the scheduler."


## Precision

Be exact about behavior, not suggestive.
- Write "Returns a list of strings" not "Returns some data."
- Write "Throws ValueError if the input is negative" not "May throw an error for bad input."
- Write "Timeout is 30 seconds" not "Timeout is fairly short."
- Distinguish "must" (requirement), "should" (recommendation), and "may" (optional).


## Structure

Documents follow a predictable hierarchy:
- What this is (one sentence).
- What problem it solves (one paragraph).
- How to use it (minimal working example).
- Configuration or parameters (table or list with types and defaults).
- Error handling and edge cases.
- Limitations and assumptions.
- Links to related docs or source code.
Do not bury the example under three paragraphs of motivation.


## Code-Examples

Every concept must have a minimal reproducible example.
- Show the simplest possible call that produces a valid result.
- Show one error case if the failure mode is non-obvious.
- Include expected output as a comment or separate block.
- Keep examples copy-pasteable. No pseudocode in API docs.


## Cross-References

Never leave the reader hunting for related information.
- Link to prerequisite concepts before using them.
- Link to deeper dives from high-level summaries.
- If a term is defined elsewhere, link the first use in each major section.
- Keep links working. Broken links erode trust faster than missing links.


## Revision-Checklist

Before marking a doc complete:
- Can a new reader follow the example without asking for help?
- Are all claims verifiable (traceable to code, test, or source)?
- Are there any ambiguous pronouns ("it", "this") that could mislead?
- Is every number, parameter, and default current with the code?
- Does the doc answer "what happens if this goes wrong?"

From NPC-Worldwide/npcsh, MIT.

More from NPC-Worldwide/npcsh