> 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. [ >8 snip ]
Code comment style seems orthagonal to me. IMO, the documentation style guide should refer only to documentation; the code style is covered elsewhere. Moreover, if we were to go there, there is not only a C style guide, but also Java coding style, shell script coding style, etc. I believe the folks doing that sort of work aren't going to come looking here for pointers to it. >> . 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. 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? My guess would be no, that path leads to madness; you will have documents which are all over the place in terms of style, readability, and even quality. The community will want, will *demand*, that OpenSolaris documentation reflect the same commitment to quality and high standards other contributors (e.g. code) are held to. If you want to write garbage, go work on somebody else's open source OS. :) - Eric
