http://qs1969.pair.com?node_id=1133709


in reply to Re^3: The problem of documenting complex modules.(Summation.)
in thread The problem of documenting complex modules.

Great! A whole website and I've got to go off, download a .tar.gz, unpack it, scrabble around inside to locate a text file called INSTALL; then scrabble around inside that for a subsection of it in order to find the documentation.

This is how they want to encourage me to use their code? Could they have made working out what it is and how to use it more obscure? Perhaps they could have encrypted it all and posted a web treasure hunt to track down the decryption keys

Yes, it can get worse: "Community driven documentation", also known as a wiki:

Publish your code, cryptic, uncommented, undocumented. Have your users document it in a wiki. Release early, release often, just to make sure that the sparse information in the wiki is outdated just after it has been posted. Also make sure that the wiki only contains information about the current version, erase all information about older versions.

And to drive users of your code really, really mad: use a forum instead of a wiki, because you don't know how to set up a wiki. Allow every troll, every spammer, every script kiddie to post nonsense. Disable the search function, "coz it killz ma serva". Use robots.txt to keep Google away, because "it killz ma serva, too".

(I've not seen that for Perl modules, but for lots of other software.)

Alexander

--
Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)