in reply to The problem of documenting complex modules.

This is very timely for me -- I'm looking into a way of developing an application that will run on both Windows and OS X (and ideally I can develop on Linux), and as part of my search I found Wx. Great, I thought, the "Hello, World!" example works -- what else ya got?

Ah, Wx::Demo. Great. Hmm.

Well, the code's installed, but there's no way to run the demo. Anyway, after a couple of dead ends, I finally figured out 

#!/usr/bin/perl

use Wx;
use Wx::Demo;

my $app = Wx::SimpleApp->new;
my $frame = Wx::Demo->new;

$frame->Show;
$app->MainLoop;

[download]
was the answer. Not terribly difficult, but I sure wish that code fragment had been added to the README. (Yes, I know I can file a bug on CPAN, and perhaps even make a pull request for the change -- I just figured this out yesterday.)

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

Replies are listed 'Best First'.
Re^2: The problem of documenting complex modules.
by BrowserUk (Patriarch) on Jul 08, 2015 at 11:19 UTC
    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!
[reply]
      '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]
        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]
Re^2: The problem of documenting complex modules.
by Anonymous Monk on Jul 08, 2015 at 22:46 UTC
[reply]

      Wow -- that's neat. It didn't occur to me to dig through the MANIFEST file, but I'll remember that for the next time. However, I think my point is still valid -- it's absolutely worthwhile to add something like my ten lines of Perl code to the documentation, so there's at least one example of how to get the code going.

      Alex / talexb / Toronto

      Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

[reply]
Re^2: The problem of documenting complex modules.
by 1nickt (Canon) on Jul 08, 2015 at 14:42 UTC

    Your demo code is excellent and I urge you to go file a PR with it today :-)

    In my experience the more concise and clear the change you are proposing, the more likely it is to be applied.

    The module authors are no doubt busy, and if they can scan and understand your proposed change in two seconds, and especially if it's to the docs, they are very likely to hit the "merge" button. If they have to squint, or spend more than ~15 seconds understanding your change, the button is not gonna get pressed. Not at that moment when they get the email about your PR. And after that, who knows when.

    Remember: Ne dederis in spiritu molere illegitimi!
[reply]
[d/l]

In Section Meditations