My 4 rules for writing (about technical things).

It isn't an accident that my writing is easy to read.

I took a technical writing course in university. I thought it was a bird course. I needed it to be a bird course - I was planning to load balance it with my "hard" CS classes.

Luckily, technical writing counted as a CS prereq. Sweet - so I could do it along with some of my harder courses!

Boy was I wrong. Technical writing is difficult.

To do technical writing, you have to write about something technical. To write is to understand, and understanding technical things well enough to write is how you write technically. If you can teach it, then you understand it.

There were a few hard and fast rules my professor left me with, that I found helpful.

1) Thou shalt not use the passive voice

2) Thou shalt not use too many words to say the same thing (Thou shalt not use too many words (Thou shalt use less words))

3) Thou shalt not use technical jargon

4) Thou shalt rewrite it. Over and over again.

Thou shalt not use the passive voice

You need to avoid the verb to be (is), no matter what. Identify nouns and remove all ambiguity.

"An oauth authorize endpoint is the place where the confidential client provides the auth code"

"Confidential clients provide the auth code over the server's authorize endpoint"

Thou shalt not use too many words to say the same thing (Thou shalt use less words)

Compression is intelligence. Compression is integration.

Source: Arxiv 2404.09937v2

Some writing limitations are actually a writing aid. Haikus are short. Human attention spans are small. Maximize the amount of bits within a piece of text. Compress.

Thou shalt not use technical jargon

People use technical jargon as effort to signal competence. Don't do that. If I cannot understand your abstract on my first read, it is bad.

Things are always simple. Complexity is added by bullshitters trying to hide the simplicity or lack of substance. Use the antisignal of simplicity. If you can afford to be understood simply, that usually means you're competent!

Thou shalt rewrite it. Over and over again.

Humans use writing as an augmentation of their minds. An ancient technology that can increase your working context. Every time you rewrite it, you compress it further. Every removed word gets closer to the core understanding.

The less baggage your ideas have, the easier it is to integrate with the rest of what you know.

Rewrite it. Over and over again.