grayrest posted a long and well-written argument for using DocBook and semantic markup
DocBook has actually been brought up before--a little more than a year ago, when there was a lot of discussion about reorganizing mozilla.org's website. I've looked at it in detail, and it does seem to be the ideal format for Mozilla's documentation. However, it is true that DocBook is intimidating; it has *so* many tags, and I haven't seen much good documentation for it. (The "official documentation"--the specification--makes the HTML spec look like a tutorial.) DocBook's advantages lie in its rich semantic vocabulary, its strict document structure (compared to HTML), its capacity for metadata, and its portability. The first two combine to make even simple stylesheets extremely powerful on a well-written DocBook page. The language is apparently well-established, and there are tools already available for working with it. Bugzilla's documentation is written in DocBook, so I'm sure Matthew Barnson knows more about the language. > filtering out distribution-specific tags or generating a > table of contents automatically or crossreferencing mozilla > terms against a glossary And the markup necessary for this, given the right tools, is already built into DocBook. Indexing, too. > I've focused most of my attention here on the online helpfiles, > but there's really no reason all of mozilla.org shouldn't go > through the same thing. hm.. Take a look at http://moz.zope.org/contribute/writing/markup (It's XML, so use Mozilla. I don't think it works in IE.)
