On Thu, 20 May 2010 09:26:08 +0100, Invisible wrote:

> Jim Henderson wrote:
> 
>> It seems that companies think "if we put a place for people to
>> comment/write/wiki/whatever they'll just participate" - and that's
>> generally not the case.
> 
> It's not just companies. I lose track of how many Haskell libraries have
> "documentation" consisting only of a list of function names and their
> type signatures. And when you say "why is there no documentation?" the
> answer you get is "patches welcome".
> 
> In other words, "if you want to write my documentation for me, I'd be
> happy to include it in the next release". I guess distributed version
> control makes people lazy.

Well, in the OSS world, there tends to be a focus on code rather than on 
documenting it.  There are some areas in both OSS and commercial software 
where documentation is pretty good - it's just rare.

>> That's a pet peeve of mine today - just software documentation in
>> general not being very high quality.
> 
> If it was only the *documentation* things wouldn't be so bad...

Documentation is relatively easy to do; software is far more complex.  
Most people expect bugs in software because of the complexity; but most 
people expect documentation that's useful.

Jim

Post a reply to this message