"Benjamin D. Smedberg" wrote: > > 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.
We've got a set of classes already; see the mozilla.org style sheet. I need to write an HTML page documenting them, though, because the docbook reference is slightly out of date. Style Guide is at http://mozilla.org/README-style.html For grammar I recommend The Elements of Style. :) > 4) The "lead editor" publishes the document. This includes assigning the > document a place in the website hierarchy I really like the idea of getting the location reviewed... > 5) Users of the document may comment on it, just like xulplanet's > comment feature. Whether or not we go for comments, the document maintainer needs to be *very clear*. If I see an error in the doc, I want to be able to notify that person without having to search CVS logs. In terms of requirements, what I most want to see is a) Clear ownership of *every* document, so one knows who to contact. b) Adding files, especially at the root, locked down so as to require location review. > It may seem that this is over-complicating the matter. If the rules and process are clear, then a little bit of complication is not a problem. If the rules and process are unclear (like they are now), even a minimal set of requirements becomes an obstacle because you have to spend so much time figuring out you're suppose to do. Further thoughts: The primary structure, as reflected in the URI, should imo be *flat* with regards to topic. e.g. /xpcom, /xpfe, /gecko, /dom, /web etc. Sections can link to each other -- for example, /gecko and /web would link to /dom. This is the most forwards-compatible structure, and for URIs that is a major consideration. Several different tocs can then link into this structure, organizing it by alphabet, by artificial hierarchy, or even by format. [1] *The format of the document should not determine its place in the primary structure.* The subject matter should. [1] I wouldn't recommend this method for mozilla.org proper, because that part of the site has more inherent structure than the collection we're trying to amass here. ~fantasai _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
