Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

Re: The problem of documenting complex modules.

by ribasushi (Pilgrim)
on Jul 13, 2015 at 05:47 UTC ( #1134444=note: print w/replies, xml ) Need Help??


in reply to The problem of documenting complex modules.

"This is meditation; but I also hope that it might start a discussion that will come up with (an) answers to what I see as an ongoing and prevalent problem."

Not sure if this is exactly what you had in mind, but I kicked off a proto-proposal based on your musings 😈

Cheers and thanks for the writeup!

  • Comment on Re: The problem of documenting complex modules.

Replies are listed 'Best First'.
Re^2: The problem of documenting complex modules.
by BrowserUk (Pope) on Jul 13, 2015 at 15:59 UTC

    That first "Ideal candidate criteria": "You have general familiarity with Perl conventions and “perlish documentation practices”"; could be a mistake.

    Imagine if instead of this, you had something like:

    my $mce = MCE->new( max_workers => 8, chunk_size => 2000, tmp_dir => $tmp_dir, freeze => \&encode_sereal, thaw => \&decode_sereal, gather => \@a, init_relay => 0, input_data => $input_file, RS => "\n>", use_slurpio => 1, parallel_io => 1, use_threads => 1, spawn_delay => 0.035, submit_delay => 0.002, job_delay => 0.150, on_post_exit => \&on_post_exit, on_post_run => \&on_post_run, user_args => { env => 'test' }, user_begin => \&user_begin, user_func => \&user_func, user_end => \&user_end, user_error => \&user_error, user_output => \&user_output, stderr_file => 'err_file', stdout_file => 'out_file', flush_file => 1, flush_stderr => 1, flush_stdout => 1, interval => { delay => 0.007 [, max_nodes => 4, node_id => 1 ] + }, sequence => { begin => -1, end => 1 [, step => 0.1 [, format => +"%4.1f" ] ] }, bounds_only => 1, task_end => \&task_end, task_name => 'string', user_tasks => [ { ... }, { ... }, { ... },], );

    And when you mousever the keys, you get a brief explanation of the parameter; mouseover the value and the default is displayed; click the key and the embedded description comments from the original above are displayed in a popup.

    Suddenly, those five screens worth of dense, complicated, hard-to-read details are all available on one screen, with a clear overview and a quick way to compare/contrast/lookup the details.

    Apply that thinking through from the top level of the module.

    Doesn't that seem a better way to both provide and explore the details of a complex module?

    Is it too late to change “perlish documentation practices” for the better?


    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!
      "Imagine if instead of this, you had something like:"
      The beginning of your reply precisely illustrates why this isn't a great idea for POD - your anchor got mangled entirely and does not (or at least originally didn't) point anywhere.
      "And when you mousever the keys, you get a brief explanation of the parameter"

      I am not seeing this mouseover effect under SCO... all I get is the "code snippet" gray thing. Can you elaborate what are you referring to?

      In any case by "perlish documentation practices" I meant "knows how POD works", not any particular specifics. For example this is how some of the APIs within DBIC are documented (this is the most prevalent, but not consistent throughout style, the project is definitely open to suggestions how to do it better).

      TL;DR: I don't think the wording perlish documentation practices is really that far off.

        The beginning of your reply precisely illustrates why this isn't a great idea for POD

        My point exactly. Why limit yourself to the lowest common denominator of POD?

        Everyone has a browser. They are the single most advanced and powerful applications available for the presentation of complex information. Why not use them natively?

        20 years ago, when a "browsers" meant lynx and man pages were cool, POD made some sense. But today?

        your anchor got mangled entirely and does not (or at least originally didn't) point anywhere.

        Not my anchor. See the first subhead beneath Synopsis at the top of the page: MCE->new ( [ options ] ).

        Unfortunately, I can't see a way past PMs html restrictions, that will allow that to be linked correctly from here.

        Anyway, just move to the second code section to see what I mean.

        I am not seeing this mouseover effect under SCO

        I did say: "imagine" :) I wasn't about to try and do a full html conversion job for the sake of a PM response. Especially as I know the author is currently restructuring and re-documenting the entire module suite.

        I was simply trying to suggest that using html, those 5 screens of dense & impenetrable information could be cleanly presented on one screen. Giving both overview and detail as required.

        I guess the bottom line is: if you think more of the same is the way to go; that's what we'll get.


        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!
        P

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (2)
As of 2020-10-26 07:31 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My favourite web site is:












    Results (250 votes). Check out past polls.

    Notices?