technical-writing

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

Address the reader as "you" in present tense, write instructions as direct commands, and put conditions before steps. Cut words that do no work, use short everyday words, and keep one thought per sentence.

Simplified Technical English (STE) is a controlled language limiting sentences to one instruction each, roughly 20-25 words, with consistent verbs per action. Use it for procedures and instructions where misreading carries real cost.

Yes, every layer except Diátaxis applies to PR descriptions and commit messages. Product UI strings are excluded since those follow product copy guidelines rather than documentation standards.

Docs read machine-written when every sentence is clipped short with no variation or viewpoint. Mix sentence lengths deliberately, state opinions in explanation mode, and prefer specific facts like "a column rename fails the build" over sterile generalities.