[FM Discuss] why documentation lags software

[Bill McConnaughey]

Andy Oram makes a lot of good points regarding the fun, rewards and 
support that surround programming vs. the drudgery of documenting it. I 
have another perspective, as a creator of software for use in my 
biophysics research lab. I always make manuals and online help. But will 
anybody read them? NEVER! They come to me with a specific thing they want 
to do and expect me to guide them step-by-step in doing it. If I try to 
instruct them, not just do their work for them, it ends up a frustrating 
waste of everybody's time. Am I just a very bad doc writer? I can't find 
out because nobody reads the damn docs.

The GUI paradigm has got everybody expecting to see buttons, dialog boxes, 
pull-down menus and the like. They don't have the attention span required 
for expressing what they want in a command line. They want to scan the 
screen with the mouse and look at the little helps that pop up until they 
find something that sounds like what they think they want do do. When it 
"doesn't work" they have no idea why. When it does work, they may not be 
able to remember how they got there.

So I am going over the CommandLineIntro, trying to learn what makes docs 
good or bad. Eventually I want to use FM to re-work and publish the docs 
for my experix project.