Comment by mancerayder
5 years ago
Exactly. That's not a documentation problem, that's a writing problem. 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. Sometimes that's also manifested in speaking, and failing to context frame concepts, arguments and ideas before jumping into excruciating detail. Senior managers notice this, and this limits your career.
So I argue that the issue is writing skills, of which technical documentation is a subset speciality of writing skills. I will add, similar to math problems or programming, writing wants you to do it over and over so it can get better.
> 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...