Re^3: Pmdev documentation

[jdporter]

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.