« Internet Book Database? | Home | Community Documentation »

April 16, 2002

Documentation is collaborative effort?

Russ Lipton: Why RTFM Won't Work [Scripting News]  Russ Lipton suggests that documentation for projects such as Radio Userland should be a collaborative effort.

I'm not sure I agree with Russ his point - at least not to the extent that the primary means of documentation is going to be community-based.  He's right on one point - "official" documentation tends to be second rate.  (O'Reilly's "the missing manual" series is a good example.) Official documentation can't admit to any faults in a product, and has to try to make sense over compromises in the product.  And there are always compromises.

One other thing I like: Russ refers to the documentation process as a spiral.  I've always said that my thinking process is a spiral.  My first time around is likely to be (very) wide of the mark, but hopefully encompasses the problem.  If I work with others, talk through the problem, we'll end up going over some of the same ground again, but each time getting closer and closer.