On Documentation: Jarle Bergersen
notes Russ Lipton's RTFM essay
, and I think he asked if I was reading.... ;-) (I don't have commenting or permalinking built in to my routines yet, but this blog seems to be fitting various needs so I'll probably get more organized eventually. ;-)
I havent used the phrase "RTFM" myself, because when that message is received from certain places it's almost always a negative reception. It's easier for people to say it chummily to each other, but out of tech support, that advice would be disastrous.
I could see "Research The Fine Manual" in many situations, because sometimes just a peek into the index would be much faster than writing something somewhere and hoping someone else understands you and finds it worthwhile to reply and that you find their response and that that response was actually useful, but researching is an easier working style to assimilate than actually reading a book about what you'll be doing.
One dynamic about software documentation is that there are strong scheduling pressures to just document what the application does. Most people would rather read documentation of how they should work. But the people who write manuals have to wrestle mightily just to learn how the software will eventually work -- docs usually get frozen for press before the codebase is frozen, and they frequently have to write about features they cannot even see! It's a lot to document the tool by ship time, and much harder to document the eventual workflow people will use.
(Rephrased, there's a difference between "How does this menu item or dialog box work?" and "How should I work if I have to connect an ASP.NET backend between a DHTML interface and an ancient commerce system?" or whatever. The latter has more value, but the former is far more practical and achievable.)
We're seeing this pattern more these days because simple software applications like text-editors and early spreadsheets have been replaced by application development environments... documentation was easier when you worried about "How do I copy text?" instead of "How do I make an application which copies text?" It's a very different situation these days.
I'm with Russ's conclusion, that the tool vendor is best-suited to describing how the tool works, but that tool users are better suited to describing how the tool is used. We see this happening already today... UDZone
, UltraDev Guru
, heck here's a bigger list
. There's a natural advantage in sharing knowledge.
That's part of what's driving this new Designer & Developer Center... folks out there know more than we in the shop do, but because we're in a central location it's our job to link all these smart people together, to help build that collective brainpower. In my group we don't know the best path to this, but we're trying multiple paths
... any feedback
about which types of resources work best for you would be great, thanks in advance.