We have roughly two different types of content that I'm aware of: reference material, and "articles".
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.
Doron and I discussed this, and I think we are approaching consensus. The references for the following material would be kept in flat files in a custom XML format:
DOM (doron has a plan for these docs, I understand)
> HTML > CSS > XML > XUL
> MathML > XBL > SVG > XPInstall
XPConnect XSLT
The spidermonkey and NSPR APIs might be future candidates for this treatment, but they already have reference material and an update strategy, so let's not mess with them yet.
This XML format would include a title, a freetext (xhtml) description, freetext remarks, basic example code, and a well-defined list of properties, methods, events, etc. It would also include standards information, if applicable. Cross-references would be in a semi-absolute format (for example <html:a href="/html/elements/body">) that would be transformed into a fully-qualified URI reference during the publication stage.
This XML format can then be transformed (using XSLT) into a displayable format for the website.
I was interested in the translation questions that were raised. I think that for the time being, unless an foreign editor steps forward, this information will be English-only. However, when the time comes that we want to translate the information, I don't think we should fork the source file; instead, we will extend the XML format a bit, to allow for the freetext sections to occur in multiple languages. Because the format is well-defined, using XSLT to accomplish the transformations is easy and allows for future expansion with little effort.
It is my opinion that these files should be kept in a CVS or subversion repository (and we have experience with CVS, so I agree with brendan: KISS, and we can always move to something else later). An automatic updater (cron job) will transform the files into the proper HTML format for the website, similarly to the way we build the mozilla.org website currently.
As for the maintenance of this reference material: it is my opinion that mozilla hackers should be *required* to update this material as they make changes to the underlying APIs. Superreview should not be granted without corresponding API updates. The lead editor should have the power to "crack the whip" for non-compliant developers.
The CVS repository should have anonymous-read access, so that any developer can easily create patches against it. CVS write access would be available to anyone with regular cvs.m.o access, and a single-review process should be established, with an editor and a short-list of peers.
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.
Articles have very different editorial requirements than the reference material above: I see the immediate need for a CMS-like workflow solution, so that articles don't get bogged down:
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.
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.
6) Translators may translate the article into another language.
WHY?
It may seem that this is over-complicating the matter. I don't think so. In particular, we need a simple way to say "good doc, please make these edits"; we also *have* to have some content-review of documents, not just editorial review. We could use bugzilla, but it's not really suited to the purpose. Please let me know what you think: I can whip up a mockup for a CMS system like this really quickly (I've done it before, for Catholic University when I was web systems guy there).
--BDS _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
