No such thing as a small change | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
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:
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!
In reply to Re^2: The problem of documenting complex modules.
by BrowserUk
|
|