|Keep It Simple, Stupid|
Pmdev documentationby ELISHEVA (Prior)
|on Aug 05, 2009 at 06:10 UTC||Need Help??|
Recently I compiled an annotated list of all of the database tables used by the PerlMonks website (see PerlMonks Data Model). bobf has expressed an interest in collaborating on it with me and I think that is a wonderful idea. In fact, we'd like it if we had an entire collection of pages that pmdev's could add remove, and edit as a group without godly intervention.
As anyone who checks the data model on my extra scratchpad will note, it is nearly at the 64K limit and there is still much information to add. It badly needs to be broken up into subsections, each with their own page. And of course those pages need to be communally edited. It would be even better if (a) we could see an edit history of all edits with undo, redo ability (b) we could assign pages to multiple categories and have category lists auto-generated (a la mediawiki). We have found both those features extremely useful on large collaborative documentation projects (including the mediawiki documentation itself!).
A collaborative environment for pmdev documentation could also be used for much more than just the annotated data model on my extra scratchpad. The documentation for pmdev is scattered in many places, including the wayback machine. A collaborative documentation environment would let us consolidate the existing documentation into an internally consistent corpus and make it easier to keep it up to date.
The ideal environment for collaborative pmdev documentation may require some work. In the meantime, bobf and I are eager to get to work and we already have some things that come pretty close to what we need. As an initial first step, we were wondering if we could copy the infrastructure used by SiteDocClan to create a set of internal pmdev documentation parallel to the public site documentation?
This would involve creating the following new nodetypes:
Using existing infrastructure also has another advantage. As we begin working on documentation together, our ideas about what we really need will take a firmer form. Once we have more experience working together, we can reopen the issue and discuss requirements with more clarity.
Best, beth and bobf