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.
I disagree, I think that consistent style among docs is important...nevertheless we can make the XHTML requirement part of the CMS by running submissions through HTML Tidy to get rid of unwanted junk and make the document compliant (e.g. properly close and nest tags).
Define "style information"... you would allow class-based styles, right?Absolutly, but the classes should be well defined for each type of document and the website maintainer would be responsible for the actual style sheets.
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".
Perhaps true, but I imagine developers who are really interested in structured tutorials who could care less about opinionated articles. That said, I have no strong views on the subject. What I would like to avoid is the way that MSDN has everything thrown together in their navigation scheme. You have no way of telling until you click a link weather you are getting into a short technical doc, a lengthy tutorial or a biased article.
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.I agree, and it makes it more likely that people will contribute if they only have to write a small doc that gets to the point quickly.
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...
Yes, I propose that the overviews be actively maintained, but I refer to short topical overviews that serve as link pages to related documents with short descriptions. These should be the responsibility of the site maintainer. More in depth technology overview are not what I had in mind in this category.
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.Most of the attributes I mentioned serve as content as well as metadata and should be displayed in the document. Whether the author is required to include them in the submitted document is another matter. They could simply include the information in a submittal form that stores it in the CMS which ultimately includes it in the header/footer etc of the document.
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]
Yeah, I am inclined to agree that I may have gone too far. I still think certain attributes should be required for certain document types and that document types should be handled differently for this reason. I see no reason why most of this could not be included as part of the CMS solution rather than strict requirements for authors.
Fred _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
