technical-writing

Diátaxis splits documentation into four modes: tutorials for learning by doing, how-to guides for task completion, reference for factual lookup, and explanation for understanding. Pick one mode per document and link between modes instead of mixing them.

Write instructions as direct commands addressed to the reader as "you", in present tense, with the condition before the step. Keep one instruction per sentence, split sentences over roughly 20 words, and avoid passive voice and words like "simply" or "easily".

Simplified Technical English (STE) is a controlled language standard that limits sentence length, enforces one meaning per word, and requires imperative procedures. It reduces misreading for non-native readers, translators, and automated parsers.

Yes, every layer except Diátaxis mode selection applies to PR descriptions and commit messages. Product UI strings are excluded and should follow your product's copy guidelines instead.

Never put reference tables inside a tutorial, tutorial hand-holding inside reference, or persuasion inside a how-to. Mixing modes confuses readers about whether they are learning, doing, or looking up facts; split the content and link instead.