Re^5: Pmdev documentation

Replies are listed 'Best First'.
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]