"Programming guides explain how to write programs that take advantage of the features of the particular product. Usage guides tell readers how to use the features of a software product." If the product is a programming language, then how would one differentiate between a programming guide from a usage guide? In this case, what is the difference between a guide that explains how to write programs that take advantage of the features of the langauge and a guide that tells readers how to use the features of the language?
"Code comment style seems orthagonal to me. IMO, the documentation style guide should refer only to documentation; the code style is covered elsewhere. " I guess the issue here is how you define the word "documentation." Does it include code comments? There is no doubt that how many spaces one indents and whether to use this_style or thisStlye to name a variable is considered coding style; but whether the comments in the source should fall under "coding style" or "documentation style" is debatable. I have no problem excluding "code comments" from this style guide; but I think it may be desirable to cleraly state that and perhaps refer to the C Coding Style or just any coding style guide for guidelines in that regard. "Key here is to answer this question somewhere: if you don't follow the documentation style in the guide, will you be allowed into the consolidation once we have an SCM repository for docs?" Yes, that would be very important. And that goes a long way to differentiating a "Doc Style Guide for OpenSolaris" from a generic "Doc Style Guide". Just an aside, if we decide to turn this guide as a something whose non-conformance may deny the entry into a repository, then I think a better name of the guide is "Documentation Style Standards". A guide is more or less optional; but standards are more mandatory. "It is called the OpenSolaris Document Style Guide, but perhaps we can make that clearer, both outside the guide itself, and within. " The title of the guide is "Documentation Style Guide for OpenSolaris" according to the title page. I guess one can differentiate between "Documentation Style Guide for OpenSolaris" and "OpenSolaris Document Style Guide" in the following sense: The former means a guide used in OpenSolaris projects, the latter may mean a guide that is developed by the OpenSolaris people which can be used in any kind of projects. To draw a parallel, a Publishing Guide for Morgan Kauffman may be a guide for writing for MK publication, and a Morgan Kauffman Publishing Guide may be a guide published by MK that teaches people how to write in any kind of publication. I am not sure whether our guide is a guide in the former sense or the latter sense. I certainly agree that there is no need to make the "Assistive Technologies" section, and the entire document for that matter, too US-centric. I was just saying that if we mention some Section 508, then I would suggest we clearly state that it refers to Sec 508 of the U S Rehabilitation Act, or better, the section of the U S code. Otherwise, a Europen or an Asian may wonder: Section 508 of what? Similarly, if we decide to cite some section 1234 of some French law, then I would suggest we say section 1234 of the French XXX Code, rather than just section 1234. The Table of Contents say the Preface starts at Page 15; actually it starts at 19. This message posted from opensolaris.org
