Michelle, > - I intend to include information about writing for > Solbook in the style guide, however, there is no plan > to open source the Solbook DTD (in short, because > Epic is not freely available). I would include the
I am not talking about open sourcing the Solbook DTD but just making it publicly available. That doesn't necessarily mean open sourcing. > info for those who will eventually want to use Solbook > templates for doc development. But, now that you bring > it up, this might be flawed thinking. How will Solbook > templates be useful without the DTD?? Not sure. You need to have the DTD to know which elements are allowed in which contexts and to validate the document. > Maybe it is more accurate to say that we'll include > information about authoring for a DTD in the style > guide beta version and leave it at that until we get > more feedback. That sounds reasonable. > -I've proposed a plan that will open source the > Solaris developer and administration documentation > XML source files, so that they can be edited with > any free editor and validated with DocBook DTD. > See the proposal thread here: > http://www.opensolaris.org/jive/thread.jspa?messageID=18528#18528 So are these books authored in Docbook, not Solbook? > - I am currently starting work on a style guide 'top ten' based > on an existing document from the editorial group, so thanks for > your thoughts on this, I totally agree that we need a condensed > version of the most important information for folks to reference. > But, I don't have any evidence that a complete, if lengthy, > style guide will alienate anyone. As a writer, more reference > information is better when I need answers to a question > during development of a piece. Don't get me wrong, a complete style guide is a very useful thing but not suited to get someone ramped up quickly. My experience with OpenOffice shows that the volunteer writers from the community want to produce results quickly. The condensed versions that you mention above would be of great help to aid anyone to produce documents quickly. The contributors' time is most valuable since most of them will do the work in their spare time. > - I also agree that concise checklists and procedures will be required to > communicate exactly how to get fixes delivered and published, and those will > logically follow once we have full-blown source control for the > opensolaris.org portal. > Right now, in absense of source control, I'm focused on helping to train > and create docs and FAQs for those writers who have agreed to act > as sponsors. Then I'll derive from those drafts, procedures for all > doc contributors that include the source control information. Thanks for taking care of that. I am excited to see how the osol documentation project is evolving and the community is growing and I am keen to help if I can. Cheers Frank
