Re^2: The problem of documenting complex modules.

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 => [ { ... }, { ... }, { ... },],
   );
[download]

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!

Comment on Re^2: The problem of documenting complex modules. Download Code

Replies are listed 'Best First'.
Re^3: The problem of documenting complex modules. by ribasushi (Pilgrim) on Jul 13, 2015 at 16:19 UTC
"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.	[reply]
Re^4: The problem of documenting complex modules. by BrowserUk (Patriarch) on Jul 13, 2015 at 16:50 UTC
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	[reply] [d/l]
Re^5: The problem of documenting complex modules. by ribasushi (Pilgrim) on Jul 13, 2015 at 17:02 UTC
Why limit yourself to the lowest common denominator of POD? Ah I see... I entirely missed this point made in your writeup. The answers are simple: Because POD is the only thing perldoc understands Because reading documentation offline is still a thing, and a quite widely-used practice Because quite frankly presentation isn't such a huge problem these days, the crappy content is This is also what I am proposing in the pseudo-grant: to get better content out there, instead of sugar-coating and spot-fixing the existing disparate, non-uniform, disagreeing docs. There certainly is value in pursuing trying to improve presentation too. But I personally do not relate to this value, and have no interest in helping pursue it.	[reply]
Re^6: The problem of documenting complex modules. by BrowserUk (Patriarch) on Jul 13, 2015 at 18:10 UTC


Do you know where your variables are?
	PerlMonks