Forgive me if the things I am going to say has already been addressed.
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. 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, applicable for writing any kind
of technical documentation. Nothing special about OpenSolaris. Actually, it
can even be construed as a guide that can be used to write tech doc for
hardware, a car, a VCR, ... 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.
2. As scope is concerned, even a doc style for "software documentaion" is too
vague. Comments in the source code is also a form of documentation. Does this
doc style offer any guidelines in that regard (i.e "each program file must have
a comment block at the top listing the file name, ...." for instance)?
3. 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.
4. 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?
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 found these useful sites: http://www.section508.gov/ and
http://www.ittatc.org/technical/experts/questions.php?sid=61c88142d1529a00e2aaf2e3eb7f6e3d#cat1)
This message posted from opensolaris.org
