Re^2: The problem of documenting complex modules.

I agree that many CPAN modules lack sufficient documentation. ... You get what you pay for. CPAN is free,

Thanks for your response. I may come back to your points once we get a few more, but at this stage I just want to make clear, the OP isn't a complaint about the documentation of any of the existing modules on CPAN. Those I mentioned or any others.

It is about trying to come up with ideas for what authors of new complex modules -- or those contributing new or amended documentation for existing ones -- can do to improve the situation.

It's not enough to just provide lots of documentation -- if it was, we wouldn't be mentioning PDL which has tons.

So, the purpose of the OP is not to complain about existing modules, but rather to brainstorm about how new modules can avoid their mistakes.

With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday'

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

I'm with torvalds on this Agile (and TDD) debunked I told'em LLVM was the way to go. But did they listen!

Comment on Re^2: The problem of documenting complex modules.

Replies are listed 'Best First'.
Re^3: The problem of documenting complex modules. by toolic (Bishop) on Jul 05, 2015 at 14:57 UTC
Your intention is clear to me, and I think it will be to others. By no means did I intend to steer the conversation in the direction of complaining about existing docs. I think my stream-of-consciousness point was that I can (and should) make the module easier to use for myself and others by contributing patches/examples.	[reply]