Re^4: Pmdev documentation

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.

Comment on Re^4: Pmdev documentation

Replies are listed 'Best First'.
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
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: data model data model overview one node for each dbtable - 83 nodes doclist containing dbtable documentation nodes one node for each settings node - 63 nodes. Setting nodes define mini embedded databases and the purpose of each attribute (and any associated handlers) needs to be explained. DBMS overview explaining what features we use and why among other things. one node for each supported DBMS - 2 nodes at present (mysql and SQLite) doclist containing DBMS nodes node class hierarchy Node class hierarchy overview One node for each nodetype - 100 nodes doclist containing all of the nodetype nodes Nodebase engine overview Database caching overview Node display categories for RAT/NN overview of RAT/NN categories overview of the RAT/NN node list generation process, e.g. handle_threaded_nodes. one node for each category - 29 nodes. Each of these comprise a subsystem handle a specific category of content. The node would list the features and explain their implementation, along with any differences from plain vanilla nodes. doclist for RAT category nodes display types: display type overview node one node for each display type - 18 or more, it is hard to count because some display types only apply to certain node subgroups a doclist for display type documentation PM markup and HTML parsing Overview of different categories of markup and where they are used. Overview of markup processing XML generation ... Theme components ... Security system and permissions architecture ... Where code lives ... Patch submission ... Bug and enhancement tracking ... Mail system interface ... Messaging system ... Edit history support ... Timestamp management ... And more ... Best, beth Update: added number of sitefaqlets and tutorials for comparison.	[reply]