Hi Paul, Great questions, here are some long answers. You wrote:
> > 1) What is the process to get a document added to the > Open Solaris Documentation Consolodation? Since you are writing for Sun storage software, you must first perform legal preparations, which I think you understand, but we can discuss offline to get you any needed advice. Then, we should update the Roadmap to reflect the timing of your source delivery to OpenSolaris--this rolls-up to the p-team and makes the rest of the project aware of your sources, so if a request sponsor comes in or a bug is filed, the triage teams know where to find you :) You should check that an appropriate category and sub-category exist for your docs in bugs.opensolaris.org. After the legal prep and roadmap update, just notify me of the location of your sources and I can add them to the tarball. It is updated each month (except March because I traveled and then got sick with the crud). As FYI, I'm prepping a new set of files to push today or tomorrow... An engineer missed their review deadline, then provided changes after the final doc was submitted, now updates, lint, visual inspection, and re-submission are underway--can anyone on this list relate? :) I always look forward to those 2-3 glorious minutes between publishing a final document and the ping that makes it obsolete... > > http://opensolaris.org/os/downloads/docs/ > ) It looks like the document must be DocBook5 XML. > Is that still the case? Right, we are in the midst of a transition now, actually. DocBook5 is certainly a valid format for sources that are delivered through the Docs Consolidation, but we also have SolBook XML files in the consolidation now too. Background: We started with DocBook5 as our standard because the community agreed that this was the best structured markup standard with the most free tools available. So, for the first year of updates to the Doc Consolidation, I took SolBook sources, converted them to DocBook5 and delivered them to OpenSolaris. Meanwhile, the community kept asking for the SolBook, which just makes good sense. To that end, I've worked with the internal Sun doctools engineer Steven Cogorno to make SolBook files editable with free tools this year. This work was beta complete in Jan, so the Feb 07 updates to the docs consolidation include SolBook files for new and updated books (yay!). The community has been testing these sources and validating that they work with existing and new scripts and tools, and I expect this transition and beta period to last through the next couple of months. (Anyone who has cycles to test the new sources in their favorite editing tool, please do so and let us know how it goes.) At least one book (os-devref) in the Consolidation was not authored in SolBook and will remain DocBook5, until there is demand to change it. The SolBook DTD is a fully conforming subset of DocBook standard, so the same scripts and tools should work for both. > > 3) Is the Documentation Consolidation the only way to > provide the source for documentation on > OpenSolaris? No, we certainly have documents and presentation slides with various different licenses (creative commons, etc.) available on OpenSolaris.org. But, for formal, structured technical documentation that includes Sun trademarks in titles and which is also provided as legally-binding support information for commercial products on docs.sun.com or elsewhere, the Docs Consolidation is the delivery mechanism that limits the most risk and, through the PDL v1.01 license, gives contributors the clearest means of re-use, modification, and re-distribution rights possible. Of course, we also house the Man Page Consolidation here too, so that is the other main delivery mechanism currently in use for documentation sources that are delivered with the code and licensed under CDDL. This may raise more questions than it answers, I do hope it is helpful. Feel free to ask follow-ups until it makes sense and question this stuff because it is a WIP and if it doesn't work for you or others or if the roadmap isn't clear, it probably is confusing for others too. Thanks! Michelle > Thanks, > Paul This message posted from opensolaris.org
