in reply to Why not a "living" PerlDoc? Others have it, why not Perl?

Well, you botched the link (Yet Another XS Tutorial), and you ignored my suggestion of AnnoCPAN :) doesn't body well :P

other boring thoughtis perl docs -- I am so sick of..., Re: facing problem in parsing xml (perlintro, perlquote) / Re^2: giving spaces (perlrebackslash)/perlrebackslash, Better perldoc on Windows

Also

Learn Perl in about 2 hours 30 minutes
chromatics free book Modern Perl a loose description of how experienced and effective Perl 5 programmers work....You can learn this too.
PLEAC - Programming Language Examples Alike Cookbook

Living documentation? I've seen it on the php site (and some others), it turns into an idiot-forum wasteland rather quickly (incoherent attempts at asking for help not realizing its not a forum, repeated for 100 comments, no cleanup, eventually culminating in 100 responses of "find a forum")... a lot like various wikis where they encourage discussion .... horrible medium for this sort of thing

Living documentation often has unstated or hidden purpose, so lots of lots of everyone mistakes the purpose of the section, so you end up having "comments" begging for everything: introduction to the language syntax, introduction to programming, introduction to computers, introduction to typing, introduction to simple english .... for every single function entry

Will you be considering alternative languages?

My suggestion, since I assume you'll be doing your own AnnoCPAN clone, see how it does annotation approval -- basically moderation -- it'll save your project; maybe

Also, ditch the existing layout (perlfunc...), give each keyword , each option its own page/heading/linktarget

Also, ditch the pod? :)

Also, ditch the pod prose formatting ; i've read someone comment they like the dense/prosy format of some of the docs because it really forces them to think and commit this to memory ;; I disagree with this; Each function/operator/construct should tell you what the name is, what the arguments are, what the return values are (and in what contaxt) in a list like format, examples also, none of this "I turned this list into prose so that you can remember it and weep for the dead list it came from thats flatter than the floor it lies on"

Also, have a perl version introduced "field" or list item or whatever ... wxPPIxregexplain.pl has some ideas like that buried here

Also, have portability "section" or list item or whatever .... for example, open, on win32 for unicode filename support use Win32::Unicode::Native

Also, have a "community tip" section ... for example readdir is low level, consider using File::Find::Rule or Path::Tiny

Also, community voting? moderator voting? downvoting? You have to be able to trim the inevitable garbage somehow ... and is it important to readers which editor edited which part or which sentence... not sure I care who added which node like it is on AnnoCPAN now ... I guess makes sense for current versions of docs ... but real perldocs don't have that, and if you're starting from scratch ... :)

Also, every single one of these things should be directly linkable, no excuse for it not to be (this part is why you might reconsider pod format and do with html/xml only)

Also, same with anchors, and no anchor mangling, if the user sees "Some heading here" the anchor should be "Some heading here" not "Some-heading-here" or a number...

Also, perldoc is already so overloaded name, taintperldoc? 2perldoc? LogicalPerldoc? LivingPerldoc?

What are your actual goals? Besides its-alive?

Whatever your goals, sounds ambitious, best of luck

  • Comment on Re: Why not a "living" PerlDoc? Others have it, why not Perl? (boring thoughtis)

Replies are listed 'Best First'.
Re^2: Why not a "living" PerlDoc? Others have it, why not Perl? (boring thoughtis)
by taint (Chaplain) on Nov 19, 2013 at 14:48 UTC
    Greetings.

    Thanks for putting so much into your reply. I had actually envisioned much, if not most of what you spoke of.
    Specifically:

    • Login/registration via valid email. won't require response, but will validate it's existence (there's a Module for that™)
    • Moderation - possibly by way of Peer Review, or at least Moderator
    • Re Sectioned - the pods are already separate, but might do well to be further broken down
    • Separate version - versions for each Perl version (separate Windows version?)
    • Convert to (X)HTML - Undecided
    • Augmentation - via Forum. I wrote a Forum back in the early `90's, and re-wrote it recently, so as to hoist it into the 21st century.
    • {...}

    Regarding Augmentation via Forum; I've seen this done before by way of a Teaser (comment on this...). That was a link to a section in a Forum. Liked it, and hated it simultaneously. Hated it, as you had no prior knowledge whether the comment you wanted to make wasn't already made by someone before you. You also end up loosing your place in the Document for no reason. Because you find someone already said that. I think a Forum would be helpful. But would never do it that way.

    As AnnoCPAN goes; I intend to insert the comments into the document(s). As opposed to placing them into the margin(s). I think that given the comments are intended to augment the current, and that (by some means) the comments have been QC'd. It makes the document overall, better.

    I also see no reason that (should I choose to leave it in pod format) it couldn't be shipped with Perl itself. Or as a diff for installations that already exist. In fact, authors of the comments could be <cite>ed throughout the document, and listed at the bottom. Which is, of course what CITE means. ;P

    I will elaborate further. But as I haven't yet finished my first cup of coffee, I've already taken too big a chance writing this much. :)

    Thanks again, for having shared such an elaborate opinion on this. I really appreciated it.

    --Chris

    P.S. Did I really overlook your reference to AnnoCPAN? (apologies, if I did)

    #!/usr/bin/perl -Tw
use Perl::Always or die;
my $perl_version = (5.12.5);
print $perl_version;
[reply]

      Or as a diff for installations that already exist
      If I understand it right, perldoc already is in a git repository (together with perl itself). If you could automatically turn this into pushes, that would be the best way (I think).

      For several postings here, both of my own and from others, I wish for a version controlled PerlMonks. Your annotation system would be another candidate for such an approach.

[reply]

In Section Meditations