Just because folks are good programmers doesn't make them good communicators. This is doubly true when it comes to written communication. It's been my experience that the mindset and thought process that makes a good programmer is usually a 180 from what makes a good manual writer. Programmers tend to ignore the fact that most manual readers A) are not programmers, B) are linear thinkers needing clear, concise instructions, and C) lack the knowledge to "fill in the gaps" for procedural issues.
I used to edit the manuals for a small company here in town. My criteria for proofing was "Can my 80 year old grandmother understand this". 9 times out of 10 the answer was a resounding NO! They were usually written in clipped, poorly worded snippets with far too many references to technical things that the average user simply could not comprehend. Then the programmers would get all in a huff when I rewrote everything. They hated me, but they started writing better manuals just to keep me from darkening the door.
In my current profession we're fighting with new MLS software. It might be process-efficient and very easy on systems resources, but it stinks in daily use. It is way too compartmentalized, the flow-through is non-existant, and nothing about it is even remotely intuitive. You have to jump around from one part of the program to another to get even the most basic tasks accomplished. The menu command structure is impossible for anyone without extensive computer experience. It's pretty obvious that the program was written by people who had no real-world real estate experience and very little idea of how to make software easy to use for non-technical types. Sure, it has all the information there, but the process it takes to wrangle it out of the program is cumbersome, long-winded, and overly complex. Plus, all the little neat "techno-weenie" bells and whistles that would be neat/fun if you have a single-use program only serve to muddy the waters here. The screen space used for neat-but-useless functions could have been put to much better use with radio buttons for the most-often needed day-to-day funtions.
And the manual is trash. Not only is the grammar and sentence structure technically terrible, it jumps around without any discernable concern for keeping the manual instructions synchronized to the process it is describing. They could have said twice as much in half the space and, with a little reorganization, made the manual ten times easier to understand. I took one look at mine and threw it in the trash. It was that bad.
Brad