Mozilla Documentation is a scattered affair. You have help for basic users in the online help, which (though outdated and in need of sanitation) covers the area pretty well. You have a lot of documents on the mozilla.org site that cover all sorts of stuff but is hard to find, and then you have tutorials elsewhere (like XULPlanet and my DOMInspector tutorial). This is not necessarily a bad thing or an unusual one, but we can do better.
Some are born to greatness and others have greatness thrust upon them. Mozilla is the latter, though we don't try to be an end user distro, we wind up with end users. Additionally, we strive to provide distributors with a "just add service" approach. While some may argue that help files are service, most of the help files can be shared across distributions. By sharing a single help file, we can pool resources (which is always a nice thing). By switching from the current semantically-dead markup in the help files to Docbook, sharing a help file becomes possible. If all mozilla documentation is in the same format, it becomes very easy to add more advanced material to the help files like how to get plugins working from plugindoc.mozdev.org (if they would like to help, my experience is that most people writing documentation are happy to see their stuff go into moz.org to help more people). If we all agree on a format, the Table of Contents can be generated automatically and glossary and other terms automatically crosslinked, and an index generated. Why XML? XML offers richer semantics for us to use, it allows us to determine what is structurally important in a document rather than marking it up to look good. Also, there is a wealth of utilities to input, output, transform, and work with XML. We can, for example, have a single help file source that is shared between Mozilla and Netscape. When one section is germane to only one browser, it is possible (and quite simple) to mark it as such and ignore it when serializing the XML to whatever format we would like help to be in. This can be extended to platform-specific documentation using the same techniques. XML processing tools make it simple to go from one form of XML to another. This may involve filtering out distribution-specific tags or generating a table of contents automatically or crossreferencing mozilla terms against a glossary, all are possible using XSL and standard processors. The rising popularity of XML same document can be used to create the online help, help on the web, PDF format help, generated as Unix man pages, even served as SVG(if we were so inclined). The stylesheet for each form would format the same file differently. One task per page of online help (as is being discussed), several tasks per page for web help (as is currently done in the help files), as a giant file (if we did man pages), and formatted and paginated in a manual format if doing PDF. It's all possible, it just depends on how much work the doc team decides to put into writing output stylesheets. Why Docbook? Docbook is a widely adopted standard that was originally developed by computer documentation writers (O'Reilley, Sun, DEC, etc.) for writing computer documentation, as such it excels at this. In case you are confused, Docbook is an XML language, much like XHTML and MathML. It's currently a completely open standard run by OASIS and is used in the Linux Documentation Project and the KDE documentation project. By using this particular DTD (a DTD is that which describes the language, XHTML is a DTD) we can leverage existing tools to convert to (some of) the various formats mentioned above. This allows us to leverage the work put into docbook by other groups and get more mileage out of the limited manpower we have. Currently, Docbook is what fits our needs closest and provides maximum bang for the buck (though bucks aren't really a unit of measure here ;-). Docbook is a bit broad and we can probably pare it down and still more than cover what we need (the KDE project does this). We may also want to extend it to provide for moz-specific features like (just speculation here) embedding code to walk the user through a task. We may even find that Docbook doesn't really fit that well (though I think it does) and want to make our own custom DTD just for mozilla. The nice thing, though, is that we can convert to our format from Docbook using XSL, which is not really possible using the current HTML documentation. An excellent piece of docbook evangelism is: http://xml.oreilly.com/news/dontlearn_0701.html Why Not? There ARE some disadvantages to this whole plan. First, nobody here really knows Docbook (including myself), so this is a sort of educated guess on my part. I'm sure this is better than the current method, it just might wind up being superseded in the future. Second, a lot of the new people volunteering aren't programmers and may be intimidated by Docbook. I believe that this isn't a problem, as it tends to be easier to mark up content than it does to write the documentation and I think that we could get volunteers to mark it up that are too busy now to do the full writing process. Side Note 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. I think it can only help mozilla's documentation state. I'd recommend talking to KDE and other open source projects on why they did Docbook and how they go about working with their documentation. Experience would be nice here. Summary: + More semantic markup, we can automate the generation of indicies and cross link with a glossary + Transform to other forms of markup and ability to format that markup at whim (separation of content and presentation) + Ability to consistently format documents across authors and switch formatting for the whole site at once (like using CSS only better) + Ability to have all platform documentation and all cross distribution generated from a single file simply managed using entities and marked sections + Ability to output to a variety of formats + Open standard that will play nice with other open source projects and distributors - Overhead in marking up the content - Adds complexity to the help file creation process - Current documentation is in HTML, does converting it to Docbook kill CVS history? It is my hope that this posting provides some impetus in switching over to docbook. I know that I will be writing my future documentation for mozilla as docbook and then transforming it to whatever format is necessary. I hope you will join me. -- grayrest http://grayrest.com/moz
