technical-writing

Diátaxis splits docs into four modes: tutorials for learning by doing, how-tos for task goals, reference for factual lookup, and explanation for understanding. Pick one mode per document by asking whether the content serves action or understanding, and learning or work.

Write each instruction as a direct command with its condition in front, such as "To delete the document, click Delete." Keep one instruction per sentence, split sentences over about 20 words, and address the reader as "you" in present tense.

A tutorial teaches a beginner through a complete learning experience where every step produces a visible result. A how-to assumes competence and gives action-only steps toward a specific goal, linking out background instead of teaching it.

Yes, every layer except Diátaxis applies to PR descriptions and commit messages. A PR body should read as a briefing a reviewer finishes in under a minute, linking logs and metric tables instead of pasting them.

Passive voice hides the actor, forcing readers to guess who does what, and pronouns like "it" or "this" can point at multiple things. Naming the actor and repeating the noun ensures each sentence parses only one way for readers, translators, and agents.