Perl Monk, Perl Meditation | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
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:
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
|
|