Re^2: The problem of documenting complex modules.

Not terribly difficult, but I sure wish that code fragment had been added to the README.

That sums the problem up in a nutshell. Often the response from authors is something along the lines of: "I've been so busy with the code that I haven't time to do 'documentation'".

But most times we aren't asking for, and don't need, reams and reams of heavily structured and typeset words; just a simple piece of code that the authors of these modules can write in a few minutes, from memory.

10 or 20 lines of code that a) compiles clean; b) runs; c) does something simple but correct.

And that isn't hard for the author(s) of packages to write; but without it, it can be days (or weeks; or never) for the new user to work out.

Authors: Eshew the 'bloody great big list of repetitively formatted apis; ditch the diatribes of personal/professional/project philosophies; don't bother with fancy graphics, cute mascots, pretty logos; don't refer me to files buried in tarballs; and don't bore me with adverts, hyperbole and marketing spiel; GIVE ME SOME CODE!

A small, complete, correct, (standalone), working example that does something simple, but vaguely realistic and useful.

After that, I can try things, read the errors, make changes, see what happens, and if I get really stuck, come back to you (or a forum) with a specific question that probably won't take anyone familiar with module more than a few seconds to answer.

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 Anonymous Monk on Jul 08, 2015 at 22:51 UTC
'That sums the problem up in a nutshell.' You should head your own advice when you write nodes here at Perlmonks. When people ask you genuine questions about your motivation, you berate them with a nasty rhetorical question that makes them sound stupid and refuse to answer their question. You are living up to the name BullyUk. You are a bully.	[reply]
Re^4: The problem of documenting complex modules. by Anonymous Monk on Jul 08, 2015 at 22:54 UTC
jeffa your death throws are sad, you've got cancer of the sundialsvc4 variety and you're drowning in the commode, soon you'll be flushed out to sea together	[reply]