There's a long tradition of "fix in documentation" - flaws in software that can't be corrected quickly enough in the software, so warrant a warning or workaround in the documentation. A lot of the time, these issues aren't actually recognized as bugs. The documenters just have to write a long explanation because helping the user work with the software requires one.
Documentation, of course, is often an afterthought, a project that's considered derivative of the rest of the work. Interface designers dream of documentation-free software, and programmers rarely consider documentation their first priority. These issues make it difficult for documentation to improve software, leaving it a passive follower rather than a potential leader.
Documentation? A leader?
Yes, actually. Something strange happens when you need to describe a process in words, and something even stranger happens when you need to describe that process in words you won't be there in person to explain. Add to that the terror induced by putting those words through a printing press for permanence and distribution, and you have a situation that requires thinking through and thinking ahead to survive.
I've known two broad kinds of writers: those who trying to sell (or evangelize) the things they write about, and those who are trying to explain. (There is, of course, a broad spectrum between those.) Evangelists sometimes find themselves forced by the difficulty of explaining their subject to change their views of it, and explainers are constantly looking for better ways to get across the fine points of complex subjects that aren't always consistent or complete.
I keep finding that authors, especially explainer authors, often find themselves trapped by the flaws of their subjects. As writers try to find paths for connecting with diverse audiences, they have to look at their subjects from a variety of angles that go well beyond determining the shortest route from A to B. Architectural or interface inconsisatencies can madden authors quickly. While writing frequently about complex topics gives writers the experience to deal with these problems, seeing the same kinds of problems over and over in different contexts often leaves writers with a strong - perhaps too strong - sense of where the gaps are.
This sense of the gaps is hard to reconcile with the ambitions of those creating the gaps. Documentation is generally meant to paper over the gaps, not expose them to readers. Readers seem to have as limited a tolerance for reading about how software won't actually solve their problems as they do for the broken software itself. I had a great technical reviewer complain about my of "dissing Rails" as I attempted to explain some tricky bits and the reason for their existence. I see similar complaints regularly from other reviewers of other authors, and occasionally they surface in book reviews as well.
The tech world doesn't seem to take writing as a strong credential. Maybe it's a sense that "those who can, do; those who can't, teach", or that writers frequently express themselves in words, not code. I was surprised how much more seriously even bad code was taken than explanations in the XML world, and that had an amazingly literate core community obsessed with specifications. Pointing this out, of course, doesn't seem to change the situation.
"Fail forward fast" is a popular mantra lately. The hard part of it, though, doesn't seem to be the "forward" or "fast" part - the hard part is recognizing and accepting the "fail" part. I can't help thinking that projects that want to get this right would be smart to make people writing about their work a key part of the process, letting them know when they've failed before projects reach a wider audience. It might be a strange reversal of the usual workflow, and doubtless it would be uncomfortable for everyone involved, but it might yield better results.