This week's book giveaway is in the Mac OS forum. We're giving away four copies of a choice of "Take Control of Upgrading to Yosemite" or "Take Control of Automating Your Mac" and have Joe Kissell on-line! See this thread for details.
My suggestion -- something that I feel has helped me a lot -- is to use a machine-checkable format, then write scripts to check everything you can. For example, write a script that checks that every menu item is documented, and every dialog box, etc. Make sure the tests run both ways -- i.e., confirm that every documented item is actually in the software. Then run these scripts as part of your application test suites. This way, when the software changes, you'll get an automatic report of where the documentation needs to be fixed.
I've used various XML-based formats for this in recent years (DocBook, homebrew), and I've used TeX in the past. Anything easy to parse is good. I guess even Word is OK if you can write scripts in Visual Basic or something that can examine Word files -- I'm not sure if this is possible or not.
Three things I learned from old IBM manuals. 1) They published two manuals for every product: a "reference manual" that showed every possible option and explained their effects in great detail, and a "user guide" that showed some typical goals and how to reach them. You can make a real mess trying to combine the two manuals. 2) A really excellent index is essential when you want to find something in a hurry. 3) Disambiguate! They never used a short article (?) when a descriptive noun would do, even if it means repeating the same noun over and over in one sentence. You almost never see "it" in a sentence.
A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Pretty often , imho, it's the obvious 'given' entity that we don't even bother explaining which will stump the new user the hardest.
Make it simple, but no simpler.. right?
Increasingly, people seem to misinterpret complexity as sophistication, which is baffling - the incomprehensible should cause suspicion rather than admiration. Possibly this trend results from a mistaken belief that using a somewhat mysterious device confers an aura of power on the user. Niklaus Wirth