> These are great questions. We've been reluctant to > present the "Sun > story" on documentation tools as we try to develop a > community strategy. > Nonetheless, you asked, so we'll give you some > details.
Thanks! :) > Sun's Solaris writers author in sgml. We have an > internal DTD, Solbook, > which is based on DocBook. It is a subset of > Docbook, that is, we have > removed many elements and attributes that we found > were unnecessary to > the documentation model and templates that we use. > > We then process the sgml source to generate XML, html > and pdf. The XML > and pdf are published to docs.sun.com. html and pdf > were included on > documentation media for Solaris 10. If it's not too much to ask, what is used to "churn out" the XML pages into HTML that we see in the web browser (i.e. Apache with mod_xml & mod_xslt, etc.)? > Style-wise, we have a Sun Editorial Style Guide. > Most of it has been > published as "Read Me First! A Style Guide for the > Computer Industry" > We also have an sgml style guide. We envision > putting out "lighter" > versions of these books that are not so Sun-centric. Personally, I wouldn't mind the "Sun-centric" approach at all. > What we need to know from you and others in the > community are what your > priorities are. > > o Is it important to be working in a consistent > format and style? This > allows for easier interchange of documentation? Interchange of documentation is not exactly a concern for me at this point: as of right now, I write my documentation in OpenOffice.org 1.1.4 using document templates and styles (some of which I customized/defined in the template) and generate a PDF. I believe that, unless you have to write/edit documentation, PDF is good enough as a target. HTML is OK too, so long as it's W3C standards compliant. > o Does the format the documentation is authored in > matter? Rather,do we > sacrifice interchange and focus instead on setting > the standards in the > areas of editorial and style guidelines and > technical content? For > example, we set rules on how something should look, > how it should be > reviewed, and output format that we post, but we pay > less attention to > how you got there? It's my belief that the focus should be on consistency of content, because in the end, it boils down to making it easy and efficient to read and understand -- consummate the content of the documentation. Having written that, some people may want to go lower than the documentation editor, so having source code which is easily understandable/readable/editable in a plain ASCII editor sure couldn't hurt. > o Are you looking for processes, rules, guidelines? Absolutely! Processes, rules and guidelines are essential to any engineering process; without them, there can really be no engineering. > o Are you looking for consistent templates for > different kinds of > documentation? (books, articles, how-tos, online > help, man pages, and > the like) Yes! One of the focal points is consistency, because inconsistent layout between documents (for example, between one book and another) can only confuse the reader. Besides, lack of consistency directly impacts the quality of the product, which is in this case information. BTW, I'm not necessarily sold on the pitch that everything must be open sourced to make it worthwhile. Technically speaking, it's completely irrelevant to me whether the tools I use are open source or not -- so long as they are freely/readily available. My concern with documentation and documentation tools is product delivery and productivity, not ideology. This message posted from opensolaris.org
