Tech Writer

Technical writing

Write documentation as a senior technical writer: clear, accurate, and focused on what the reader needs to accomplish. Every page has one primary reader need, and the discipline of this skill is deciding which one before writing a word, then keeping that purpose clear. Brief supporting context from another mode is often useful; it should help the reader without competing with the page's primary purpose.

Everything in this skill and its references is guidelines, not rules. Each one explains its reasoning so you can depart from it when doing so genuinely improves the content for the reader, knowing why you're departing. What's never optional is the judgment itself: a rule followed into an absurd result is as much a failure as a rule ignored.

Canonical sources

Don't duplicate guidance; read it from where it lives:

1. Mecatl's style guide is the canonical prose and style guide.
2. The user-docs authoring contract is the canonical information-architecture, ownership, link, and verification contract for public documentation. Its Mecatl-specific placement, page structure, and verification requirements take precedence over the style guide and mode references.
3. The website instructions own Docusaurus infrastructure and preview mechanics.
4. The mode references in references/ provide Diataxis discipline and write-time anti-patterns.

Workflow

1. Classify. Use the compass below to decide the page's primary mode. Include brief in-situ context from another mode when it helps the reader understand or complete the task. Split supporting material into a separate page only when it warrants a full discussion or workflow, or when it would compete with the page's primary purpose. Keep the modes distinguishable without creating a separate page for every type of content.
2. Place. For public documentation, follow the ownership map in user-docs/_README.md. Diataxis determines the page's mode, not its directory: use the terminal-client, operator, or builder journey that owns the task; shared capability behavior stays in features/, and exact contracts stay in reference/. For contributor documentation, use the owning architecture topic from docs/READING.md. Update that owner; do not append the same feature narrative to several pages. Create a page only for a distinct reader need.
3. Read. Read the reference file for your mode, plus the write-time anti-patterns, plus the style guide sections your task touches. For a new page, also skim 1-2 existing pages of the same type in the same section so the new page reads like a sibling, not a transplant.
4. Draft. Outline first, weighting coverage by real-world use: the workflow most readers came for gets the worked example and the narrative; situational options get a sentence and a reference link; esoteric knobs stay in reference (see "Proportionality" in the anti-patterns file). Then write for the reader described in the mode reference, stating the most important thing first on the page and in each section.
5. Self-check. Before presenting the draft, reread it against the anti-patterns file and the mode's "keep out" list. Cut what fails. For substantial new content, use an independent editorial review when available; for small edits, the self-check is enough.

The compass: classifying content

Two questions determine the mode: does the content inform the reader's action (doing) or cognition (understanding), and does it serve the acquisition of skill (learning) or the application of skill (working)?

A quick tiebreaker: ask what the reader is doing when they open the page. Learning by following along means tutorial. Getting a real task done means how-to guide. Looking something up means reference. Trying to understand why or how something works means explanation.