Which kinda leads me to another reason I'm opposed to the plan: it creates a very regrettable precedent.

I think viewing this proposal as "per-group" documentation is the wrong way to go about it. I see it more as a way to keep a complex and cohesive body of documents together. Obviously some group has to have responsibility for maintaining the set of documentation, but that doesn't make it group documentation. Group documentation describes the group itself. If a group had a really complex set of internal policy documents and sub-documents, then maybe it might be a good idea to put them in their own document collection with their own master list containing collection specific strings, documents, doclets, and faqlets. But if not, a wiki would do just fine and I expect the group wouldn't even want more.

Your point about end-users wanting to know technical details of the site is a good one. However, it has more force (to me) as an argument for making the readership open to all monks. It doesn't justify mixing up the documentation into a single pool where all editors have to be members of the SiteDocClan. Even though there are users who want to read technical documentation and pmdevs who want to read end user documentation (of course there are), that doesn't mean that they want the two types of documentation mixed up together.

Perhaps it would help to explain a bit how much documentation there really is? The 20 or so pages in the Everything Bible is misleading. It simply does not give enough information to do anything except make trivial patches to nodes. To really understand the system one needs much more. Just considering the material I've collected so far (or see the need to collect) we have 300+ nodes and quite a few distinct doclists (incidentally there are only 211 sitefaqlets and 247 Perl tutorials). I'd really like to have one master list to keep track of all of the docstrings, doclists, doclets, and faqlets involved in building technical documentation. Here is a sampling:

Best, beth

Update: added number of sitefaqlets and tutorials for comparison.

In reply to Re^7: Pmdev documentation by ELISHEVA
in thread Pmdev documentation by ELISHEVA

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.