|No such thing as a small change|
New pmdev-only documentation infrastructureby jdporter (Canon)
|on Dec 03, 2010 at 18:01 UTC||Need Help??|
Following up on previous thread Pmdev documentation...
I've been cogitating a bunch upon this idea of using sitedoclets to document code, i.e. infrastructure nodes.
Anyway, I've come up with what I think is a pretty good idea, so I'd like to run it by you all, see what you think.
My idea essentially is this: have a new nodetype, devdoclet, which would be used to document the purpose and usage of infrastructure nodes. In particular, it would be a great place to note the status of nodes such as dead, live, experimental, and not-yet-live htmlcodes .
devdoclet is like sitedoclet in most ways, except that,
That is, the doclet for (say) parselinksinchatter is necessarily parselinksinchatter devdoclet. (It would therefore be slightly different from the sitedoclet situation, where this nomenclature is conventional but not universal nor enforced.)
This enables certain very convenient things — most obviously, that a pmdevil can navigate from a devdoclet to its associated code node simply by stripping off the " devdoclet" part of the title. (Of course, we'd automate this for you by means of a link in your pmdev nodelet.)
I also envision a structure, perhaps somewhat like the sitefaqlet/faqlist nested-listy thing, for knitting all the devdoclets into a whole "site infrastructure document"... as touched on in the earlier thread. And note that it would also be possible to make devdoclets which are not linked to specific infrastructure nodes; these could be used to document overarching concepts and like such as.
In the new regime, sitedoclets are used for storing content which is to be embedded/included in some other displayable object (such as a superdoc or nodelet); and devdoclets are for writeups which serve to document infrastructure nodes, such as htmlcodes and htmlpages. Only pmdevils will have the ability to read/write the latter. sitedoclets remain the bailiwick of SiteDocClan.
What is the sound of Windows? Is it not the sound of a wall upon which people have smashed their heads... all the way through?