Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw
 
PerlMonks  

Re^5: The problem of documenting complex modules.

by ribasushi (Pilgrim)
on Jul 13, 2015 at 17:02 UTC ( [id://1134545]=note: print w/replies, xml ) Need Help??


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

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.

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

Replies are listed 'Best First'.
Re^6: The problem of documenting complex modules.
by BrowserUk (Patriarch) on Jul 13, 2015 at 18:10 UTC
    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
Domain Nodelet?
Node Status?
node history
Node Type: note [id://1134545]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others wandering the Monastery: (7)
As of 2024-04-16 18:02 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found