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

In reply to Re: Why not a "living" PerlDoc? Others have it, why not Perl? (boring thoughtis) by Anonymous Monk
in thread Why not a "living" PerlDoc? Others have it, why not Perl? by taint

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.