An engineer’s best tips for writing documentation devs love

The first tip: Respect readers' time. Thank you. There's often so much crap to cut through. And as the author writes, almost everyone skips it anyway! There can be some real time sucks.

Another good one to keep in mind is using accessible and inclusive language. There's so much dev lingo and slang that is can be challenging for people to learn and communicate.

We recently discussed the Diataxis framework in a brownbag talk ( https://diataxis.fr/ ) - I find this is a helpful guideline when it comes to writing documentation.

"People skip the text! They go to the code! So make sure that you're using real-world problems for it..."

I think this is also the reason why sites like Indie Hackers became famous.

People got tired of reading "documentation" (i.e. advice written in the second person, "do this", "don't do that", etc.)

Instead, they wanted to read "real-world" problems&stories on how people solved the "problem"/built a startup out of nothing.

Good points.

Haha "The only thing worse than no documentation is incorrect documentation." Choose meaningful variable names! Your made-up jibberish is worthless!