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.
Currently, sitedoclets can be attached to infrastructure nodes of the following types:
Update '10/12/22; see belowAnyway, 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,
- It is owned (creatable, editable) by pmdev rather than SiteDocClan, and would not be intended for general public consumption.
- More importantly — there is an explicit policy which supports bi-directional links, implicitly by title, between an infrastructure node and its devdoclet.
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.
Thanks...
Update:
2018-12-18
The new nodetype devdoclet and the associated htmlcode showdevdoclet have been created.
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.
|
---|
Replies are listed 'Best First'. | |
---|---|
Re: New pmdev-only documentation infrastructure
by jdporter (Paladin) on Dec 17, 2018 at 20:26 UTC | |
Re: New pmdev-only documentation infrastructure
by jdporter (Paladin) on Dec 22, 2010 at 21:07 UTC | |
Re: New pmdev-only documentation infrastructure
by jdporter (Paladin) on Dec 23, 2010 at 17:34 UTC | |
Re: New pmdev-only documentation infrastructure
by jdporter (Paladin) on Dec 23, 2010 at 16:55 UTC | |
Re: New pmdev-only documentation infrastructure
by jdporter (Paladin) on Dec 22, 2010 at 20:19 UTC |