Ming Kin Lai wrote: > "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?
In the case of a programming language I would imagine it would be a language reference guide and the distinction between user and programmer wouldn't be made since they would be in fact the same audience. > "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. Code comments, when used properly, are not documentation but are in fact an integral part of the code which exists for maintenance purposes. Some software projects use tools which generate documentation from specially formatted comments embedded in the code; using such tools is a matter of convenience, and even in such a case the distinction is still clear. > "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. Yes this is a very good point, and "Standards" versus "Style Guide" is a good way of wording it to provide the distinction. > "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. Right. If it's just a style guide for documentation then it needn't refer to OpenSolaris and in fact it probably should not. If OTOH the style guide is part of a OpenSolaris accepted documentation standard (which doesn't exist yet) then using OpenSolaris seems appropriate. My 2c would be to drop "OpenSolaris" from the style guide since it's just a guide and not a standard. The license also gives folks the ability to apply these guidelines to their own projects outside of OpenSolaris. But others may have differing opinions. - Eric
