Greetings, and thanks for chiming in. > 1. I would suggest there be some mention of the scope > of the application of the Doc Style Guide. It is Doc > Style Guide _for OpenSolaris_; but there is nothing > mentioned about OpenSolaris.
It is called the OpenSolaris Document Style Guide, but perhaps we can make that clearer, both outside the guide itself, and within. Michelle? Sue? > The Preface says: "The > Doc Style Guide for OpenSolaris provides guidelines > for a consistent approach to writing technical > documentation." "This style guide is for developers, > ... who are involved in the publication of various > types of documentation." From the description, it > sounds like this is just a general doc guide, It is. There is a section (that may expand) that discusses how to target the document one is writing to the particular type of audience the author is writing for, be they developers, administrator, average users, etc. This guide is meant o be a roadmap for how to write proffessional documentation, according to "best practices", much as Sun does for their official documents. Keep in mind though, that it is still a beta. The authors have done an amazing amount of work, but it isn't finished. > Actually, it can even be construed as a guide that > can be used to write tech doc for hardware, a car, a > VCR, ... Yep. Again, we can maybe clarify more that this is for OpenSolaris, but beyond that, yes. The scope can apply to anything that relates to OpenSolaris. Hardware is a very legitimate area, such as talking about getting x86 motherboards to work properly, what drive controllers work, etc. > The objective of this guide is therefore a > bit vague. If this style guide is to teach people > how to document, then it should set an example of > documenting precisely what this guide (i.e. the > product) is, to begin with. It does. It is fairly clearly a guide to writing documentation. It also does by example--the guide tries (very successfully, I think) to abide by the rules and guidelines it sets out. > . I would suggest there be some mention of the > authorativeness of the Doc Style Guide. Is it > "approved" by some OpenSolaris steering committee? > Is it mandatory? Probably not, but it is nice to > document that. As with many (most?) things in OpenSolaris, nothing is definitively authoritative. With that in mind, the documentation group is trying to lay out some "best practices" guidelines, much like many other groups here. Most of the documentation (except the links to the official Sun docs) do not follow these guidelines yet. The hope is that, as people see the value in professional documentation practices, they will become more interested in either following the guide directly, or allowing others to take there document and "clean it up". > . Chapter 8 "Types of Software Manuals" : I cannot > see the difference between Usage Guide and > Programming Guide. And how about changing > "Programmer" to "Programming", "User" to "Usage" in > the bullet list? This has been discussed, and I think Michelle is still mulling this one over (which way to go). She's been very busy, so we haven't preassured her. :-) But you point is well taken. I don't even remember for sure which way I fell on the discussion. (I _think_ I went for the more "active" terminology; Michelle can thwap me, if need be.) > 5. It would be more informative to relate Section 508 > to the Rehabilitation Act. And it would be nicer to > point to the U S Code section into which Section 508 > is codified. I believe this was the "Assistive Technologies" section? We had a discussion about this--we want feedback from people everywhere, and not make it too "US-centric". OpenSolaris is meant to be global. (There was a discussion in another forum recently about time zones, and how even foreign locales used the US TZ name, for example.) Other countries (I'm thinking especially of Europe, but even my home of Canada) have different regulations, some of which may even be stricter than those in the US. So far, we haven't had anyone chime in with non-US references, but I would argue we keep it open. that's not to say we don't do anything until then, but I'm not sure where this is on the roadmap. (I haven't written anything for the OSSG; I've just kibbitzed a bit, hopefully constructively.) Rainer This message posted from opensolaris.org
