Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

Re^4: The problem of documenting complex modules.(Summation.)

by afoken (Canon)
on Jul 08, 2015 at 11:23 UTC ( #1133709=note: print w/replies, xml ) Need Help??


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". ;-)

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1133709]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others musing on the Monastery: (6)
As of 2020-08-05 11:55 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Which rocket would you take to Mars?










    Results (35 votes). Check out past polls.

    Notices?