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.
I think that ultimately, it depends on the how the lead editor wants to do things; they will define the process.
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
Interesting point, but I think you go too far. See below about document types.
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
I think that forcing people to use XML is an unwelcome barrier. Let's be realistic, people are gonna write these long docs using their favorite editor, be it Mozilla Composer, Dreamweaver, or by hand. The content is the important part, not the format.
No style information should be allowed in the document. Each document
Define "style information"... you would allow class-based styles, right?
Document Types: Benjamin has opined that DevMo documentation can be divided into reference materials and articles. We would be severely
I was dividing by maintenance strategy, not website organization. But I see there is at least one category I left out, which is FAQ/overview documents which need continued updating, but are not strictly formatted like the references.
Technical Notes: These are short 2-5 paragraph documents that give very White Papers: In depth documents that cover the theory and possibly Specifications: Documents such as RFCs fall into this category and
> Articles: I would not define these documents as broadly as Benjamin > Tutorials/HowTo: These documents, such as Neil’s XUL Tutorial, tend
The practical differences between these types are minimal. They are all "write-once, don't update" documents (if you need to update the document, you re-submit it as a new whatever). Yes, the editor should link them from different places in the document hierarchy, but don't over-design; there are going to be many docs that "cross the boundaries".
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.
IMO a decent search engine beats a FAQ every day. Let's go with small technical notes, abundantly cross-referenced. We can use databases+ XSLT to combine technical notes into FAQs later, if the need becomes obvious.
Overviews: These documents serve as general overviews of products or technologies and contain links to the most recent or most valuable related documents.
Are you proposing that overviews be "actively maintained"? This is the hardest part... I can write a good overview of a moz technology, and it will be completely out of date in 6 months. I don't have a good solution...
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.
Firstly, metadata should probably not be stored in the document XML itself. In particular, if we go with a CMS system, the CMS would keep track of the metadata for us.
Secondly, a single set of markup guidelines is far better than a complicated hierarchy. I propose something simple like:
The document will be stored as a fragment of HTML or XHTML.
Authors should use markup that reflects the structure of the
text. The following CSS classes are available: pre.code { whatever...}
[etc]--BDS _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
