Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

Re^3: The problem of documenting complex modules.

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


in reply to Re^2: The problem of documenting complex modules.
in thread The problem of documenting complex modules.

"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.

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

Replies are listed 'Best First'.
Re^4: The problem of documenting complex modules.
by BrowserUk (Pope) 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
      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.

        I entirely missed this point made in your writeup.

        No. I don't think you did. It just isn't an either/or scenario.

        The point you thought I was making was indeed a big part of the points I was making; but so is presentation.

        For example: This detailed and entirely accurate piece of English text is a UK local government body complying with its statutory requirements:

        A path from a point approximately 330 metres east of the most south-w +esterly corner of 17 Batherton Close, Widnes and approximately 208 me +tres east-south-east of the most southerly corner of Unit 3 Foundry I +ndustrial Estate, Victoria Street, Widnes, proceeding in a generally +east-north-easterly direction for approximately 28 metres to a point +approximately 202 metres east-south-east of the most south-easterly c +orner of Unit 4 Foundry Industrial Estate, Victoria Street, and appro +ximately 347 metres east of the most south-easterly corner of 17 Bath +erton Close, then proceeding in a generally northerly direction for a +pproximately 21 metres to a point approximately 210 metres east of th +e most south-easterly corner of Unit 5 Foundry Industrial Estate, Vic +toria Street, and approximately 202 metres east-south-east of the mos +t north-easterly corner of Unit 4 Foundry Industrial Estate, Victoria + Street, then proceeding in a generally east-north-east direction for + approximately 64 metres to a point approximately 282 metres east-sou +th-east of the most easterly corner of Unit 2 Foundry Industrial Esta +te, Victoria Street, Widnes and approximately 259 metres east of the +most southerly corner of Unit 4 Foundry Industrial Estate, Victoria S +treet, then proceeding in a generally east-north-east direction for a +pproximately 350 metres to a point approximately 3 metres west-north- +west of the most north westerly corner of the boundary fence of the s +crap metal yard on the south side of Cornubia Road, Widnes, and appro +ximately 47 metres west-south-west of the stub end of Cornubia Road b +e diverted to a 3 metre wide path from a point approximately 183 metr +es east-south-east of the most easterly corner of Unit 5 Foundry Indu +strial Estate, Victoria Street and approximately 272 metres east of t +he most north-easterly corner of 26 Ann Street West, Widnes, then pro +ceeding in a generally north easterly direction for approximately 58 +metres to a point approximately 216 metres east-south-east of the mos +t easterly corner of Unit 4 Foundry Industrial Estate, Victoria Stree +t and approximately 221 metres east of the most southerly corner of U +nit 5 Foundry Industrial Estate, Victoria Street, then proceeding in +a generally easterly direction for approximately 45 metres to a point + approximately 265 metres east-south-east of the most north-easterly +corner of Unit 3 Foundry Industrial Estate, Victoria Street and appro +ximately 265 metres east of the most southerly corner of Unit 5 Found +ry Industrial Estate, Victoria Street, then proceeding in a generally + east-south-east direction for approximately 102 metres to a point ap +proximately 366 metres east-south-east of the most easterly corner of + Unit 3 Foundry Industrial Estate, Victoria Street and approximately +463 metres east of the most north easterly corner of 22 Ann Street We +st, Widnes, then proceeding in a generally north-north-easterly direc +tion for approximately 19 metres to a point approximately 368 metres +east-south-east of the most easterly corner of Unit 3 Foundry Industr +ial Estate, Victoria Street and approximately 512 metres east of the +most south easterly corner of 17 Batherton Close, Widnes then proceed +ing in a generally east-south, easterly direction for approximately 1 +6 metres to a point approximately 420 metres east-south-east of the m +ost southerly corner of Unit 2 Foundry Industrial Estate, Victoria St +reet and approximately 533 metres east of the most south-easterly cor +ner of 17 Batherton Close, then proceeding in a generally east-north- +easterly direction for approximately 240 metres to a point approximat +ely 606 metres east of the most northerly corner of Unit 4 Foundry In +dustrial Estate, Victoria Street and approximately 23 metres south of + the most south westerly corner of the boundary fencing of the scrap +metal yard on the south side of Cornubia Road, Widnes, then proceedin +g in a generally northern direction for approximately 44 metres to a +point approximately 3 metres west-north-west of the most north wester +ly corner of the boundary fence of the scrap metal yard on the south +side of Cornubia Road and approximately 47 metres west-south-west of +the stub end of Cornubia Road.

        Now see what a little presentation does for presenting the exact same information data, thus converting it to information:

        All distances are in meters; directions are ordinal points (using the abbreviations for North East South and West); and they are approximate.

        A path between the Foundary Industrial Estate, Victoria Road and Cornubia Road, in Widnes.

        • From 330m E of the SW corner of 17 Batherton Close, and 208m ESE of the S corner of Unit 3 Foundry Industrial Estate
        • going ENE for 28m to 202m ESE of the SE corner of Unit 4, and 347m E of the SE corner of 17 Batherton Close,
        • then N for 21m to 210m E of the SE corner of Unit 5 and 202m ESE of the NE corner of Unit 4
        • then ENE for 64m to 282m ESE of the E corner of Unit 2 and 259m E of the S corner of Unit 4
        • then ENE for 350m to 3m WNW of the NW corner of the scrap metal yard boundary fence on the south side of Cornubia Road, and 47m WSW of the stub end of Cornubia Road

        be diverted to a 3 metre wide path

        • from 183m ESE of the E corner of Unit 5 and 272m E of the NE corner of 26 Ann Street West,
        • going NE for 58m to 216m ESE of the E corner of Unit 4 and 221m E of the S corner of Unit 5
        • then E for 45m to 265m ESE of the NE corner of Unit 3 and 265m E of the S of Unit 5
        • then ESE for 102m to 366m ESE of the E corner of Unit 3 and 463m E of the NE corner of 22 Ann Street West,
        • then NNE for 19m to 368m ESE of the most E corner of Unit 3 and 512m E of the SE corner of 17 Batherton Close,
        • then ESE for 16m to 420m ESE of the S corner of Unit 2 and 533m E of the SE corner of 17 Batherton Close,
        • then ESE for 240m to 606m E of the N corner of Unit 4 and 23m S SW corner of the scrap metal yard boundary fencing
        • then NW for 44m to 3m WNW of the NW corner of the scrap metal yard fence and 47m WSW of the stub end of Cornubia Road..
        • Because POD is the only thing perldoc understands

          That's like writing motorway signposts in pheromones because that's all horses understand.

        • Because reading documentation offline is still a thing, and a quite widely-used practice

          I read all my module documentation off-line. In my browser!

        • Because quite frankly presentation isn't such a huge problem these days, the crappy content is

          Sorry, but given that full 2/3rds of the DBIx::Class pod is made up of a bloody great big list of author names; I think you should reaccess 'presentation'.


        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!

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (6)
As of 2020-10-19 15:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My favourite web site is:












    Results (205 votes). Check out past polls.

    Notices?