Comment by routerl

> A lot of tech people don't enjoy writing, but also they're sometimes not very good at predicting or empathizing with the future reader of their writing.

Agreed, wholeheartedly. Will hitchhike on your comment to recommend two things: Brett Victor's pdf stash [1] and, specifically, the Walter Ong essay "The Writer's Audience is Always a Fiction"[2].

Long story short, we form our audiences by subjecting them to our writing. In writing software documentation, we are implicitly informing the next generation's thought by the simple power dynamic that underlies all technical documentation: "you must understand this in order to do your job properly".

It is no wonder that "form", "inform", and "information" are such closely related words.

We dictate the level of rigor and intelligibility we expect out of our technical documentation, when we write technical documents. It almost sounds like a tautology when put this way, but "bad docs" are exclusively the result of a professional culture that puts up with the existence of bad docs. I've been there; too tired and overworked to care about writing something properly, or wanting to avoid writing a doc enough that I setup some autodoc thing and called it a day. We literally don't get paid for writing documentation.

But good documentation is what made us into good developers (if we are good developers). We should get paid for doing that...

[1] http://worrydream.com/refs/

[2] http://worrydream.com/refs/Ong%20-%20The%20Writer's%20Audien...