Re^2: Pmdev documentation

Some questions:

Is there any benefit to having two easily identifiable but separate corpuses of documentation? Having a separate node type makes it ridiculously easy to write a query that extracts only the development documentation or only the user documentation. If they all share the same node type then we can only separate them by hand tagging them.
Is it possible that we may want some special behavior, data or a toolkit that applies to dev documentation but not end user documentation? Having a separate end-user and dev documentation nodetypes would allow that more easily.
Are there any security concerns in making pmdev documentation part of site documentation? The entire monk community is a reader of site documentation, not just the cabal.

Given these questions, I think it might make more sense to have a supertype "PmFaqlet" from which both "SiteFaqlet" and "PmdevFaqlet" inherit. Or alternatively, make "PmdevFaqlet" inherit from "SiteFaqlet". This gives us the most flexibility down the road.

On the other hand, I think it is more important that we move forward while the enthusiasm is high. If creating separate nodetypes is going to take an inordinate amount of time (more than a week), then provided we have a way to hand tag the pmdev documentation, I'd rather get something less than ideal now and clean up the mess later.

Best, beth

Comment on Re^2: Pmdev documentation

Replies are listed 'Best First'.

Re^3: Pmdev documentation
by jdporter (Paladin) on Aug 06, 2009 at 12:17 UTC

Is there any benefit to having two easily identifiable but separate corpuses of documentation?

Yes. The better question is, How much benefit is there, and is it the worth the costs? The subsequent question is, What is the best way to implement it? "Easily identifiable but separate" is pretty abstract. I think the end could be achieved by using the existing sitefaqlet/faqlist infrastructure; the dev docs would be kept in a separate set of faqlists, for example.

a query that extracts only the development documentation

Extracts? What for? Having the dev docs in their own faqlists would make it easy enough, for practical purposes. More important, I think, would be the implications for Super Search. Would we want it to search the dev docs? IMHO, probably yes. But if not, we could rig Super Search to skip the dev docs (except for pmdevils, maybe). I've already begun work on an infrastructure for making Super Search ignore faqlets which are linked in certain faqlists. It could be used for this as well. Also see my answer to the Security question below.

Is it possible that we may want some special behavior, data or a toolkit that applies to dev documentation but not end user documentation?

Yes. I would say that at such time as we identify such a thing, it will be easy enough to create the new node types and convert the existing docs. I'd argue for deferring just on the You Arent Gonna Need It principle.

Are there any security concerns in making pmdev documentation part of site documentation?

If we don't want non-cabal to read these docs, we could make them alphafaqlets. In fact, this is what I would recommend.

But note: currently only SiteDocClan can create/read/edit alphafaqlets. I have submitted an enhancement request for alphafaqlet access to be expanded to all of Cabal; but so far, it has been tabled by the gods. Now would be a great time for them to reconsider it. :-)

I think the bottom line — the essential fact — is that converting nodes from sitefaqlet to pmdevdoc (or whatever we call it) , at such time as that type is created, will be trivial. I agree with you - let's get started on the docs, and worry about the infrastructure later.

Between the mind which plans and the hands which build, there must be a mediator... and this mediator must be the heart.

[reply]


Pathologically Eclectic Rubbish Lister
	PerlMonks