Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

New pmdev-only documentation infrastructure

by jdporter (Canon)
on Dec 03, 2010 at 18:01 UTC ( #875241=pmdevtopic: print w/replies, xml ) 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.

Currently, sitedoclets can be attached to infrastructure nodes of the following types:

        Update '10/12/22; see below

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,

  1. It is owned (creatable, editable) by pmdev rather than SiteDocClan, and would not be intended for general public consumption.
  2. 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.


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?
  • Comment on New pmdev-only documentation infrastructure

Replies are listed 'Best First'.
Re: New pmdev-only documentation infrastructure
by jdporter (Canon) on Dec 23, 2010 at 17:34 UTC
Re: New pmdev-only documentation infrastructure
by jdporter (Canon) on Dec 22, 2010 at 21:07 UTC

    As a sort of first half-step in this direction, I've added the ability to attach sitedoclets to the following additional nodetypes (with more to come):

    In the case of the above (10 nodetypes, so far), the sitedoclet, if any, is shown on the default view of the node (i.e. ;displaytype=display).

    In addition — and perhaps most radically of all — I've also added the ability to attach sitedoclets to any node for which ;displaytype=viewcode works (except patches). That is, in addition to most of the above, the following nodetypes:

    Again — the sitedoclets (if any) belonging to such nodes can be accessed when viewing the node with the viewcode display type.

    And as usual, if there is no sitedoclet currently attached, a link labeled Create sitedoclet appears where the Edit sitedoclet link would be.

    And I suppose this is a good a time as any to explain to those of you who may not know, there are really two different uses for sitedoclets: one is a way to attach a documentary node to some other node, with an implicit (though very binding) association by node title. For example, if we wish to make an internal document for quest display page, the doclet would be named quest display page sitedoclet, and it would be visible when viewing the node in question. The other use for sitedoclets is to store fragments of HTML content intended to be shown to the user. For example, the text at the top of SoPW is pulled in from a sitedoclet, and the content of several of the nodelets is stored in sitedoclets. There are two different functions for these two use cases: for the former, use showsitedoclet, and for the latter, use get_sitedoclet. Functionally, the differences are small: showsitedoclet will render a Create or Edit link (along with the actual content, if any), while get_sitedoclet returns html intended to be embedded in some containing context (or an empty string, if doclet no existe). get_sitedoclet provides a way to retrieve only delineates parts of a doclet, and a way to expand macros within a doclet. The use of get_sitedoclet does not have the strict naming convention that showsitedoclet does.

    showsitedoclet is only used in the display pages of certain nodetypes, as detailed above.


    It seems rather natural to convert the one use of sitedoclet - the showsitedoclet case - into the proposed new notetype!

    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?
Re: New pmdev-only documentation infrastructure
by jdporter (Canon) on Dec 23, 2010 at 16:55 UTC

    And if we're going to make a new nodetype, whose functionality is separate from the existing sitedoclet, we have the freedom to design it so that it really meets our needs, rather than feel conceptually constrained by our ideas of sitedoclet. Among other things, we could use hard linking to associate the doc and its referent, rather than the "symlinking" currently used with sitedoclets.

    To do that right, we have to understand what our needs are. How do we want this thing to work? The first question, to my mind, is: Should it be a single authoritative "document" which authorized users can update, or do we want threaded discussion?

    I believe that we definitely do not want the latter, though it would be fun to implement. We could use note, which is the essential node for threading, and we could set the parent/root pointers to the referent node (the one being documented). In our case, we'd probably want to use pmdevnote, as it is identical to note except for who's authorized to access them. These are already being used for threads spawned under patches.

    One nodetype which is a hybrid of the two approaches is categorized answer. The main document would be a "static", updatable node, with a pointer back to its referent; and discussion could spawn below it as necessary.

    Just about any editable node can be made editable by a group simply by giving node ownership to the group.

    wiki is a nodetype specifically designed to support growing content and collaborative editing. It does not have parent/root pointers, however.

    In some of these cases, we'd want to clone the existing type to a new type; in other cases, we could use the existing type as is.

    Bottom line - It looks like sitedoclet is probably as good a starting point as any. :-)

    So, what, if any, are the downsides of basing it on sitedoclet? For one, we'll probably have to continue the title-based implicit linking scheme — assuming we don't want to add fields, which would necessitate creating a new db table — which I think we'd prefer to avoid, if possible. But note that this constraint pertains with any nodetype not derived from note.

    Which makes me think... Maybe we start with pmdevnote, since it has the fields we want, and simply customize its code to be like that of sitedoclet. And we'd add in some of the growth/collaboration support from wiki code. Yes. This is probably the way to go. :-)

    The "symblic linking" scheme isn't particularly bad, however: the relevant node titles are generally static and unique. The exception (on the second point) is patches, but we don't want to do this with patches anyway, I don't think. Those support threaded discussions already.

    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?
Re: New pmdev-only documentation infrastructure
by jdporter (Canon) on Dec 22, 2010 at 20:19 UTC

    So.... I'm gonna need you to just go ahead and start implementing this. Mmkay? That's great.

Log In?

What's my password?
Create A New User
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (6)
As of 2017-02-23 04:19 GMT
Find Nodes?
    Voting Booth?
    Before electricity was invented, what was the Electric Eel called?

    Results (339 votes). Check out past polls.