[specialist]

"current state of generally terrible technical writing"

I've served the technical writing role a few times.

If it (your product) is hard to describe, you probably did it wrong. At the very least, keep trying until things make sense. Better mental models, metaphors, workflows, whatever.

I was once asked (by a school principle, former writing teacher) why software developers are such terrible writers. I replied that all the good software developers I know are also good writers. That if you can write an essay, you can also code. The problem is that most people are terrible writers, programmers included.

I will admit that writing is harder than programming. Because people are far more interesting, complicated, nuanced than computers.

Reading someone else's code is the closest thing we have to mind reading. More so than prose. IMHO.

Miscommunication and ambiguity is the norm. We all just have to accept that and keep trying.

[dublin]

Not only that, the very idea of clear, literate explanations is really a core part of the entire Internet ethos, heavily influenced by UNIX. (Read http://theody.net/elements.html - you'll be glad you did...)

This was revolutionary back in the days when most protocol specs were proprietary and designed to protect the priesthood (usually of a particular vendor)rather than facilitate interoperability. It's hard to imagine now, but one of the big reasons TCP/IP won was that it actually encouraged interoperability and interworkability. (Jan Stefferud drew a distinction between those two terms in this context...)