Hi Brendan, I would just like to clarify that the source for this comment:
Zone documentation from the Solaris 10 FCS era: "an administrator > could have different versions of an operating system running concurrently > on one physical system." is not any version, past or present, of the System Administration Guide: Solaris Containers--Resource Management and Solaris Zones. The concept of a single version of the OS is fundamental to the zones technology. I would not have written a statement to the contrary, and I would not be alive today to respond to this message if I had (the zones engineers would have killed me when they reviewed the doc :-). Thanks, Penny Brendan Gregg wrote On 01/14/06 08:17,: > G'Day Folks, > > I've been reading through the style guide, and previous comments here. > > On Fri, 13 Jan 2006, Michelle Olson wrote: > > >>Hi George, >> >>Welcome and thanks for chiming in, +1 from me. I expect the tools to >>take care of formatting for me, my concern is the technical accuracy of >>content and good coverage of the tasks, concepts, and reference >>information. Style and consistency are important to me, but generally >>take a back seat... > > > About accuracy vs style, > > I agree with the Michelle's comments above the most (+1). The best > documentation I use is that which is accurate, detailed and explains how > a technology is intended to be used. The style can be improved > afterwards, once the "beef" is there. > > Documentation that is clearly buggy, that lacks crucial details and > leaves no clue about usage, isn't very useful. Even if it is well written. > It may be fixed afterwards - after causing untold havoc with customers > (eg, Zone documentation from the Solaris 10 FCS era: "an administrator > could have different versions of an operating system running concurrently > on one physical system." - oops!). > > > About the style guide, > > It's a good reference, especially if I want to write official Sun > documentation. And if I follow every point, then what I write will look > like official Sun documentation. > > I see two main types of documentation contribution, > > 1. If an OpenSolaris contributer wants to write OFFICIAL documentation > that ends up on docs.sun.com (especially for a topic Sun would not > normally find the time for, eg "writing an FMA messaging agent"), then > reading a 278 page style guide should be the least of their problems. > Representing Sun in such a formal capacity can't be taken lightly, and > writing such authorative documentation is hard work. If the contributer > accepts that, and Sun accepts their work, then great. > > 2. If an OpenSolaris contributer wants to throw together some informal > documentation for opensolaris.org (so long as it's accurate > documentation), a summarised version or a checklist style guide would be > much better. It may not look like official Sun documentation - but > perhaps this is desirable. If some OpenSolaris documentation looks like > Sun wrote it, customers will believe Sun wrote it and may take it TOO > seriously. > > Most of the documentation I would want to write would be the second type. > I'm not sure what others had in mind - if we were to do more of the first > or second type? > > Improving man pages may be another type that contributers can help with... > > ... > > Back to the style guide: I haven't found a discussion on content yet > (probably as it's a style guide, not a content guide). Would it help to > have a section on content? For example, > > Recommended Content, > > - history of the technology: predecessors, similar products > - why the technology exists: concepts, problems it solves > - feature list > - strengths and limitations: compared to similar products? > - usage summary: with pictures > - tasks covered in detail > - usage with other products: eg, Sun Cluster > - supported configurations > - recommendations and best practices > - list of real world scenarios > - examples of real world usage > - reference information: websites, books > > Sometimes I encounter documents that are little more than a reference of > command line options, and leave all of the above to the imagination.... > > ... > > PS. page 129 on the style guide has a broken link, > http://opensolaris.org/os/community/documentation/glossary > > cheers, > > Brendan > > [Sydney, Australia] > > > > _______________________________________________ > docs-discuss mailing list > docs-discuss at opensolaris.org
