Technical writing

writing.md

Advice for Technical Writing

Picking something to write about

Write the article you wish you found when you googled something.

Write at the moment of learning

Comparing technologies is an underused format

Careful with that intro

tell me what this article is going to get into and who it is for

Careful with the title, too

A nice clear blog post title: Getting Started with GraphQL, Phoenix, and React by Margaret Williford

A terrible version of the same: Build a web app with modern technologies in 30 minutes!

The outro

Ben Halpern says that the next most important thing after the intro is: [...] the last paragraph.

Make it scannable

subheadings are probably the easiest and most powerful trick for scannability.

Lists, images, illustrations, videos, blocks of code, tabesl, collapsing sections

Use an active voice

Passive: "After the file is downloaded..." Active: "After you download the file..."

Passive: "The request is processed by the server." Active: "The server processes the request."

There are lots of words to avoid

Simply Clearly Just Of course Everyone knows Easy However So Basically Turns out In order to Very

Be mindful of your tone

Friendly. Authoritative. Welcoming. We're all in this together. Flexible (nondogmatic about ideas). Thankful.

Careful about length

1000-1500 words

Don't stop yourself from writing

"Meh, everybody already knows this," you might think. (They don't). "What if I'm wrong and someone calls me out?" (You aren't wrong if what you're doing is working for you.)

There is no one perfect style

Just write.

The more introductory, the higher the bar

You only need to be clear, and clarity is valuable to readers at any skill level, not to mention appreciated by them as well.

But the bar isn't that high in general

Abstraction is helpful, but real-world examples are sometimes better

Blogging opens doors

You get better at what you do

Your voice alone < A story with context < Stories including others < Research and data along with stories including others

Are you pitching?

Are there any useful tools?