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:

• DevFaqlet:: similar to sitefaqlet. These would be used for group edited documentation pages. pmdev's should have full rights to add, delete, and update the pages. Deleting is important because leaving around irrelevant documentation can be very confusing. When pages are broken down into subpages, one doesn't always get the arrangement right the first time. It is important to be able to reorganize information easily without leaving the old not-so-good organization lying around. The cabal should have read access.
• DevFaqlist: similar to faqlist. These would be used to thematically group devdoclets. pmdevs should also be able to add, remove, and edit these lists at will. The cabal should be able to read them.
• DevFaqstring: similar to faqstring. Again, pmdevs should also be able to add, remove, and edit these at will. The cabal should be able to read them.

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

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.