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.
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. The tools we use to generate the XML, html and pdf were internally developed based on commercial products-- a problem in an open source world. 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. Right now we are trying to figure out how we can scale all this for an open source community. Yes, we'd like to influence the community toward an sgml/xml model. At the same time, we recognize that we can't just impose our model, as we believe it cannot be fully supported with open source tools. 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? 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? o Are you looking for processes, rules, guidelines? We envision a doc project site managed by our community leaders. Each project or piece of documentation would have an owner who would manage the contributions to that project or documentation. For open source documentation that originated within Sun, we would regularly update it with contributions from the community and from within our Sun writing staff. The community would be able to post to the site through the community manager, as well as download open source documentation. o Are you looking for consistent templates for different kinds of documentation? (books, articles, how-tos, online help, man pages, and the like) Our roadmap is posted within the documentation community site. We anticipate some changes in emphasis based on community input, and we hope to flesh out more details to post for you very soon. We encourage feedback so that we can better understand your needs and requirements. Thanks, Sue Sue Weber, Program Manager-Solaris Documentation Nevada, Express, Trusted and OpenSolaris (650) 786-5467 x85467 susan.weber at sun.com This message posted from opensolaris.org
