Hi Ming, Welcome to docs-discuss and thank you for these detailed comments on the Style Guide. You make good points here, many of them we have not heard before, so again I appreciate your time to send review comments. I have provided responses inline below:
> 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. That is correct. 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. I think that the 'About this document' section is accurate, but I'm open to any ideas you have for text that better describes it. For my part, I wouldn't think that this guide could teach a person how to write documentation. But, if you feel this is something that we should try to do, I'm open to that idea, and I'd support your efforts to do so. I believe that such a project would involve materials that describe the basics of the research process and English composition. If you are interested in just developing a list of major considerations for doc style used in OpenSolaris, please contribute your ideas here, where we're beginning that discussion: http://www.opensolaris.org/jive/thread.jspa?threadID=7270&tstart=0 The goal of the style guide today is to help writers to improve technical documentation, by highlighting topics that are of particular importance to the reader of technical docs, based on historical knowledge about tech doc development gathered at Sun. > . 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)? Ah, this is an excellent point, and maybe this is one area where we could clarify scope as you suggest above. We don't make recommendations about code comments, so we can add this to the description of the document and provide a link to the C Style Guidelines, because I believe this is traditionally thought of as good coding style for OpenSolaris. See http://opensolaris.org/os/community/documentation/getting_started_docs/cstyle.ms.pdf on page 7 code comments are described. This is just my assumption, so others please chime in with thoughts to the contrary on the division between code style and doc style. > . 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. OK, would you also add this to the 'About' section of the document in the Preface? I'm happy to add this information, just let me know where you'd expect to find it. > . 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? Good catch, this should match the new titles that were suggested in the last round of edits, so I'll make this change. > 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) Excellent, I will add these links also, thanks so much for your help! I will also add you to the contributor list in the next version--I hope to update the document in the coming two weeks. Regards, Michelle This message posted from opensolaris.org
