There has been a lot of discussion on the documentation list the last couple of days about developer.mozilla.org. In an effort to move the discussion along, I have attempted to distill the issues that are still outstanding and offer proposed solutions or guidelines for some of them.
Technology Requirements: The most popular subject thus far has been what technologies will be used to implement the site. Arguments have been made for and against CVS, Doctor, Wiki, and various CMS. It is my opinion that the technology that we end up using should be driven by the policy decisions and guidelines that are formulated for the rest of the outstanding issues, many of which have not yet been discussed at all.
Licensing Requirements: I have no opinion, but obviously this issue must be resolved. MSDN documents are published under various licenses and I see no reason why we could not do the same as long as we are given the right to publish. I do think it should go without saying that all documents published on DevMo should have appropriate attribution whether the document’s license requires it or not.
Submission Requirements: I agree with Clover that documents should be subject to spell checking, grammar and to some extent readability. Documents should also be required to be properly marked up pursuant to some specification document that we publish on the site.
Update Requirements: I have to disagree with Brendan about the need for CVS style versioning of documents on DevMo. My reasoning is that documents on DevMo should never be updated or edited once they are published. All documents should be properly classified and marked up pursuant to published guidelines that specify the relevancy of the document in terms of product versioning and dates. Authors who wish to publish subsequent versions of documents should be allowed to add links from outdated documents to the most recent version, but both should remain published. Two document types, FAQs and Overviews (see Document Types below) would be exempt and allowed to frequently update documents.
Mark-Up Requirements: Using XML has many advantages, but transforming existing documentation may prove difficult. Using XHTML Strict markup has many of the advantages of XML and can easily be parsed into XML using HTML Tidy or similar if we choose to use XML only in the future. No style information should be allowed in the document. Each document type should have a firm specification for required elements and allowed tags. Elements would be specified using the class attribute of the respective tag.
Classification Requirements: Each document should be properly classified using the following attributes: publication date, relevant technology (e.g. XUL or XPCOM), relevant product (e.g. FireFox or Thunderbird), topic and document type (explained below). Some documents, depending on type, may not have all of these attributes and some may have more than one value for some attributes. Documents will be marked up according to a standard that includes these attributes.
Document Types: Benjamin has opined that DevMo documentation can be divided into reference materials and articles. We would be severely limiting ourselves if that was the case. Document types should be more clearly delineated in order to allow for easier browsing, searching and mark-up specifications. I have gone over much of the current developer documents on Mozilla.org and reviewed many of the documents on MSDN and other developer networks. Although there is no definitive classification mechanism, I have categorized developer documents into the following categories:
Technical Notes: These are short 2-5 paragraph documents that give very specific information about a particular topic. Although I was unable to find any current Mozilla documents in the format, I found several lengthy documents that may have been better organized as several tech notes.
White Papers: In depth documents that cover the theory and possibly detail about a new or proposed technology or technological approach. These documents are more free form than other types of documents because they often include pictures, charts, graphs and references.
Specifications: Documents such as RFCs fall into this category and generally have their own specific formatting requirements. We may not choose to include this type of document or we may choose to include summaries with links.
Tutorials/HowTo: These documents, such as Neil’s XUL Tutorial, tend to follow a predictable format and have special mark-up requirements.
References: Benjamin’s post deals quite well with these types of documents.
Articles: I would not define these documents as broadly as Benjamin did. An article, first and foremost, would not fall into any of the other document categories. In general, an article requires only text (if it contained images it is probably a tutorial) and outlines the author’s views on a particular technology/product/tool/trick and so on.
FAQs: These documents require frequent updating and have special mark-up requirements. We may or may not choose to publish these types of documents, preferring to publish individual technical notes for each FAQ instead.
Overviews: These documents serve as general overviews of products or technologies and contain links to the most recent or most valuable related documents.
Mark-Up Proposal: Each document type should have specific requirements for correct mark-up. In addition, specific attributes, used for classification, search etc, should be required.
Technical Notes Required Attributes:
Title
Applies to
Date
Last Reviewed
Related Information
Keywords
Technical Notes Allowable Mark-Up:
hr, p, aWhite Papers Required Attributes:
Title
Author
Date
Keywords
White Papers Allowable Mark-Up:
Any XHTML Strict tags with no style information.Tutorials Required Attributes:
Title
Applies to
Date
Last Reviewed
Related Information
Keywords
Tutorials Allowable Mark-Up:
Generally follow LDP guidelines with optional images and class attributes for each type of source code listing.
Articles Required Attributes:
Title
Author
Date
Introduction
Body
Conclusion
Articles Allowed Markup:
h1, h2 etc, p, aOverviews Required Attributes:
Topic
Updated
Overview
Links should be marked up by document type
Overviews Allowed Mark-Up:
h1, p, aFAQ Required Attributes:
Topic
Date
Question
Answer
FAQ Allowed Mark-Up:
h1, p, aComments, suggestions, flames encouraged ;-)
_______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
