technical-writing

Apply four layers: pick one Diátaxis mode per document, address the reader as "you" with active voice, limit each sentence to one thought under 25 words, and remove any sentence open to two readings. Cut every word that does no work.

Diátaxis splits docs into four modes: tutorials (learning by doing), how-tos (steps to a goal), reference (facts for lookup), and explanation (understanding and why). Each document should use exactly one mode, with links where modes meet.

Write each instruction as a direct command with one action per sentence. Put the condition before the step, keep articles like "the" and "a", and never use passive voice or narration such as "the component must be installed".

Yes, PR descriptions and commit messages are treated as writing too. Every layer except Diátaxis mode selection applies to them, including cutting filler words, using real symbol names, and avoiding ambiguous pronouns.

Product UI strings are not documentation and should follow your product's copy guidelines instead. Also, when a rule makes a sentence worse, fix the sentence another way or leave it alone; the rules serve the reader.