writing-artifacts

writing-artifacts

A durable artifact has readers you will never meet, arriving with zero conversation context, often skimming, sometimes another agent. Write for that reader. This skill is a system to write toward, not a list of things to avoid: supply the right structure and the slop has nowhere to live.

Stance (adopt before writing)

You are a competent colleague showing the reader something you have both, in principle, access to. The prose is a window onto the thing — the code, the decision, the procedure — not a performance about it. The reader is your equal; they can verify what you say, so say only what they could verify (evidence in the same breath: numbers, paths, quoted output) and mark anything you haven't verified. Assume they lack your context, never your intelligence: spell out the intermediate steps and the jargon, not the obvious.

Document layer — give it one job

Before writing, answer in one line: who arrives at this document, and what did they come for? Then give the document that one job (Diátaxis):

• Learning a skill by doing → tutorial (a lesson; you drive, they follow, it must work).
• Getting a task done now → how-to (steps to a goal; they're at work, respect that).
• Looking something up while working → reference (facts, structured for lookup, no digressions).
• Understanding why, away from the keyboard → explanation (discursive, context, trade-offs).

When one document must serve two jobs (a README usually must), separate the jobs into sections rather than blending sentence-by-sentence — mixed types bleed and serve neither reader. Use the types as a compass, not a filing system; don't scaffold empty sections.

Order the whole document bottom-line-first: purpose and outcome in the first paragraph, general before exceptions, background last. A good README's first paragraph lets most readers stop reading, satisfied.

Paragraph layer

One point per paragraph, stated in the first sentence; the rest is support. In procedures: one action per step, condition before command ("If the build is red, do not deploy" — never the reverse).