Technical Writing

Write for humans and machines. Every sentence earns its place or gets cut.

Core Principles

Lead with the point. First sentence = the takeaway. Context comes after, if needed.

One idea per unit. One point per sentence. One topic per paragraph. One concern per section.

Concrete over abstract. Name the thing. Show the example. Skip the preamble.

Active voice, imperative mood. "Add retry logic" not "Retry logic should be added" or "Added retry logic."

No filler words. Cut: "basically", "simply", "just", "in order to", "it should be noted that", "as mentioned above", "please note that", "going forward". If removing a word doesn't change the meaning, remove it.

No hedging unless uncertainty is the point. Say "This will break X" not "This could potentially have an impact on X."

Prefer short words. "use" over "utilize", "start" over "initialize", "show" over "indicate", "about" over "approximately."