I wish you had been there too. That was in fact the entire conversation, and you are quite correct, the precise nature of tye's concerns were not explored, though perhaps they should have been. Hopefully, tye will add a more detailed explanation of his concerns to this thread.

I, of course, don't feel as uncomfortable with tye's decision as you do.

For one, I find the idea of mixing up site documentation with pmdev documentation very confusing. Sitedocs are end user documentation. pmdev docs are developer documentation. Different kinds of people volunteer to write them. They need different editorial styles and appeal to entirely different audiences. For decades we've been shipping applications with seperate technical and end user documentation, precisely for these reasons.

I also think you are seriously underestimating the number of nodes needed to do a good job of development documentation. If we were only talking about 4 or 5 nodes, a manually maintained faqlist would problably work well. However, I've never documented a system this complex with so few nodes. Nor have I seen any other comparable system documented well with only 4 or 5 nodes.

But even if it were true that we can fit all the documentation into 10 or so pages of solid unbroken text (640K), cramming as much as possible onto each page would hardly be advisable:

Would you still consider a manually maintained faqlist a good way to manage documentation if we had 20,30,50,100 nodes? I would contend that we'd be spending a lot of time simply making sure all the nodes we created ended up on that list. On the other hand, if the nodes are part of a separate node type it just happens automatically. We can then spend the management time on something more useful.

You suggest that wanting new node types violates the YouArentGonnaNeedIt principle. However, that principle applies to adding features that you don't have any use for (yet). Adding new node types doesn't add new features. It reuses existing features (sitedoc infrastructure, node types, inheritance) for a new purpose. By your own admission the rationale for creating new nodetypes (permissions) is legitimate. And even if we were adding new features, we'd be adding something we'll use right away, not at some fuzzy time in the future.

Finally, in Re^3: Pmdev documentation, you suggest there is a cost to adding new nodetypes but you haven't elaborated what costs you are concerned about. It is hard to have a discussion about costs that aren't specified.

In theory, we should be able to create a set of subtypes of SiteDoclet etc and be done with it. After all, we only want to change the permissions and the Everything engine supports inheritance for all of the rest. Unfortunately, the first few htmlcode nodes I've looked at all have "SiteDocClan", "SiteDoclet", etc hardcoded throughout. This leaves us with the following options:

  1. copy all of the relevant nodes and then do a massive search and replace. This adds yet another N htmlcode etc nodes to the mix, but it may be the least disruptive)
  2. refactor the nodes with hardcoded strings. Instead derive this information from the nodetype. This would eliminate the need to copy,search,and replace. And if we ever wanted to do this again, it would save us time in the future. On the other hand, PM doesn't really have a robust test environment, so maybe copying is safer. If we break anything, at least we'll be breaking something only a few people need to use rather than a widely used production system.
  3. copy and refactor. Eliminates risk of disrupting existing systems, but still adds N new nodes that are very similar to existing nodes. On the other hand, we could use the pmdev documentation to test the refactoring and once we gained confidence we could gradually move the sitedoc to the refactored solution and get rid of the almost alike nodes.
  4. Begin documenting in sitedoc, but work on one of the above solutions. When the pmdev nodetypes are done, change the nodetypes on the documentation.

My own preference is for 3+4: temporarily using sitedocs while working on option 3 (make and refactor copy). I am concerned about the time involved in refactoring and the very slow run-debug cycle (since I can't apply patches or create a development server). On the other hand, I don't know whether even temporary residence in sitedocs would be a problem and that brings us back to the question that wasn't really discussed: how having pmdev docs mixed in with sitedocs affects search logic.

Best, beth

In reply to Re^3: 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.