I've been reading the discussion with interest, and want to layout some ideas for structure/metadata/organization:
We have roughly two different types of content that I'm aware of: reference material, and "articles".
I think that's probably too simplistic, see me post "DevMo Guideline Proposal"
REFERENCE MATERIAL
Reference material, e.g. the MSDN "DHTML Reference" at
http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/dhtml_reference_entry.asp, includes DOM/HTML/XUL/SVG documentation, XPCOM interface documentation (both frozen and non-frozen), xpinstall API reference, etc.
This material has the following characteristics:
* It needs constant updating as mozilla adds support for new DOM/etc specifications.
* It needs to be deeply and widely cross-referenced.
* We want to keep historical information available (e.g. mozilla started supporting document.load() in release x.x, and XMLHttpRequest in release y.y.
I agree that the developers should keep the documents up to date, but I think the document should only be published for each public release of the software and older reference docs should remain online. In other words, the maintenance of the document should not necessarily be part of the CMS.
ARTICLES
article: a many-paragraph text, with (optional) attached code samples, diagrams, and supporting files. An article may be a "howto", sample code, overview, or other document.
Again, I think that there are different types of documents based on purpose, content, need for review, etc.
1) anyone may submit an article for consideration. Articles may be submitted in any language (although if we don't have an editor for that language, we might be in trouble). Articles should be in html, and use a well-defined set of CSS classes from a standard stylesheet, so that there is graphical consistency. There should be a style+grammar guide for consistency. All code samples and figures/images should be included in the submission. The submitted must agree to whatever licensing scheme is chosen.
2) a group of "peer editors" may accept with edits, suggest resubmission with changes, or reject the article outright. Ideally, the article would have feedback within 4-7 days. Peers should run the doc through a basic editing checklist including making sure that code samples actually compile/work, etc.
3) Once an article is accepted, experienced mozilla coders (module owners, peers, superreviewers) would review the doc for accuracy. This shouldn't be a serious time-consumer; most docs should take 5-10 minutes to check. Again, feedback would occur within 4-7 days. These can also make edits directly, or ask the article author to make edits.
Using the document categories I suggested in my post, steps 2 and 3 should not be necessary for "Articles", "Tutorials" or "White Papers" because they are "contributed unofficial documentation". Nevertheless, the editor may wish to be able to add comments to these types of documents.
4) The "lead editor" publishes the document. This includes assigning the document a place in the website hierarchy and linking it from other places as necessary. The lead editor is also responsible for "see also" links
5) Users of the document may comment on it, just like xulplanet's comment feature.
Tutorials and Articles yes, Tech Notes and White Papers no.
_______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
