Re^3: Pmdev documentation

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:

Editing 64K page of documentation just isn't practical. Every save brings you back to the top of the document, scrolling back down over and over again is error prone and time consuming.
Technical documentation benefits greatly from rich hyperlinking and hyperlinking works best when documents cover short discrete topics. If each topic has its own document, then we can link to the topic by linking to the document. If we cram topics into a page until we run out of space, then we have to do links internal to the document. These links tend to be a lot more work to set up (we have to manually add <a name="blah"> tags. They also tend to be less stable: it is all too easy to wipe them out simply by editing the document. Link rot can also happen with document ids, but it is a lot easier to write a program to find those than it is to write a problem to verify "#blah" links.
Crowding too much information onto a page tends to strangle the various subtopics on the page. A topic is more likely to get full detailed treatment when it has a page of its own.
Moving detailed topics onto their own page makes overview pages easier to scan. They can then become learning tools that give new developers a chance to see the big picture. In a complex system overview pages are especially important because they help people understand the range of things to be learned.
If the documentation is well organized, overview pages also help people blackbox parts of the system that they don't have time to learn. This means that someone can get up to speed on a particular part of the system without having to understand the whole.

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:

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)
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.
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.
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

Comment on Re^3: Pmdev documentation Download Code

Replies are listed 'Best First'.
Re^4: Pmdev documentation by jdporter (Paladin) on Aug 10, 2009 at 02:57 UTC
I find the idea of mixing up site documentation with pmdev documentation very confusing. Sitedocs are end user documentation. pmdev docs are developer documentation. I think that is a false dichotomy. Pmdev members are users too. If you look at the PerlMonks FAQ, you see that there is a pretty good variety of docs, targeted at all classes of users. In fact, there is a subset of the FAQ which I think will disprove your claim. How confusing have you found it that the site doc set contains Janitors' Guidelines and Janitor Powers? In fact, I think it's quite common, and fair, that users who aren't janitors can know those things about how the janitors work. And in further fact, there have been innumerable instances of ordinary users expressing interest in how PerlMonks works under the hood. And adding a section to the doc set for the pmdev stuff would be just what they're looking for. (Update: another example is Editing DocLists, a sitefaqlet only needed by SiteDocClan and Pedagogues.) They need different editorial styles and appeal to entirely different audiences. Irrelevant to the question at hand. If we were only talking about 4 or 5 nodes, a manually maintained faqlist would problably work well. But that is precisely the kind of system you've been asking for! The only difference between the system of new nodetypes you've proposed and the existing sitefaqlet/faqlist system is which group owns the nodes. Would you still consider a manually maintained faqlist a good way to manage documentation if we had 20,30,50,100 nodes? That is what we have now. And while I wouldn't claim it's ideal, by any stretch, I find it adequate. And I haven't heard you suggest a better system. You suggest that wanting new node types violates the YouArentGonnaNeedIt principle. I did not make such a broad, generic statement. I said that wanting a new nodetype to support a small, relatively static handful of nodes, without any peculiar access requirements (as in this case) violates the principle. However, that principle applies to adding features that you don't have any use for (yet). No, it applies to adding features that you don't need (yet). Adding new node types doesn't add new features. It's true that adding new nodetypes doesn't necessarily add new features; but I would say if adding a new nodetypes doesn't add new features, then it is a complete waste. But then, I'd say that a specific scheme of access controls qualifies as features, so I don't think we have a disagreement here. you suggest there is a cost to adding new nodetypes but you haven't elaborated what costs you are concerned about Ah, you did a great job summing up the issues there. I have to confess I'm not surprised. :-) 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. Well, "sitedoc" is rather imprecise. So it depends on whether we're talking about sitefaqlets or alphafaqlets. Alphafaqlets are not visible outside Cabal and are not searched by Super Search. If we want pmdev docs to be "outside the mainstream", then this nodetype would work. But I've pretty much come to the opinion that the docs should be public, just like Janitors' Guidelines and Janitor Powers. Anyway, I don't think there would be any problems either way. I also think you are seriously underestimating the number of nodes needed to do a good job ... cramming as much as possible onto each page would hardly be advisable I'll say what I said before: let's start the job using the tools we already have at hand; and then we'll really know, based on experience, where that system is inadequate, rather than guessing now how it might be. 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. Well, it doesn't automatically happen automatically; we have to make it happen automatically. Anyway, what you're describing sounds exactly what we already have which inserts new perltutorials into New Tutorials. (It's done in perltutorial maintenance create, btw.) Between the mind which plans and the hands which build, there must be a mediator... and this mediator must be the heart.	[reply]
Re^5: Pmdev documentation by ELISHEVA (Prior) on Aug 12, 2009 at 17:50 UTC
No, it applies to adding features that you don't need (yet) And that I think is the nub of it. Because you can't see any real benefit to separating technical from end user documentation, you conclude it isn't something we need and everything else follows. Since I (and others) do see benefit, we conclude otherwise. But I wonder, would you really feel the same way if it you weren't so worried about the technical issues? After all, keeping technical and end user documentation in separate collections is pretty much an industry standard. I find it hard to believe that you don't see any reason ever to keep technical and end user documentation in separate collections, but maybe you do. Best, beth	[reply]
Re^6: Pmdev documentation by jdporter (Paladin) on Aug 12, 2009 at 19:09 UTC
you can't see any real benefit to separating technical from end user documentation It's not that I don't see any benefit; I certainly do. The crux of the issue, for me, is the separation: How are we to implement that separation? I contend that having it in a separate faqlist, or family of faqlists, is quite adequate. And not only adequate, but in fact we wouldn't want it to be any more separate than that. But that's jmho. Anyway, as I said before, this is a false dichotomy; pmdev are users, and non-pmdev users have an interest in how PerlMonks works. So keeping the technical documentation in the same library, but on a different shelf, makes plenty of sense. And there's already some precedent for putting cabalistic docs in the FAQ system — not that they couldn't be moved, if it came to that. would you really feel the same way if it you weren't so worried about the technical issues? Maybe not. :-) It's hard to say. I find it difficult to put the technical issues out of my mind. But I do know that implementing your scheme will require far more work than simply deriving new nodetypes from sitefaqlet&faqlist with Creator/Updater/Deleter set to pmdev. Which kinda leads me to another reason I'm opposed to the plan: it creates a very regrettable precedent. Because if we do this for pmdev documentation, why should we not also do it for janitors documentation, and for QandAEditors documentation, and SiteDocClan documentation, and Power Users documentation, and gods documentation, and Pedagogues documentation, and Cabal documentation? And maybe even moderators documentation as well? Between the mind which plans and the hands which build, there must be a mediator... and this mediator must be the heart.	[reply]
Re^7: Pmdev documentation by ELISHEVA (Prior) on Aug 12, 2009 at 20:54 UTC