Sorry for the late reply--been a hectic weekend.
> 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.
Agreed. This is where someone could take the documentation and (perhaps after
testing it for accuracy) massage it into something that more formally meets the
Style Guide. If the accuracy isn't there, though, there's no point massaging it
into anything.
> Documentation that is clearly buggy, that lacks
<snip>
> on one physical system." - oops!).
I think many admins (myself included) have been on the pointy end of this
stick. :-( This is why I think some sort of testing for accuracy, preferably
by two or more people, may benefit the process. Specifically, do this _before_
the massaging of the document.
> 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.
Hmm. I hadn't even considered that these contributions would become "official
Sun documentation", really. I figured that there were two very different
categories:
1) OpenSolaris documentation
2) Suggestions to Sun to add notes or expand upon the existing Sun
documentation (I made a suggestion of the sort regarding the usermod man page
through a different venue a couple months back.)
I this is also a venue to contribute to official documentation, then great.
Three ways to contribute, and a broader range of opportunity.
> 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.
Agreed. In this "third channel", the Style Guide becomes crucial. Again, it may
be worthwhile to have someone contribute the text, and another the massaging.
Do we maybe want to impliment some semi-official channel to facilitate such
collaboration? When it comes right down to it, some technical people just
aren't very good writers, and it would be a shame to lose their expertise
because the quality of writing isn't up to snuff.
> 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.
Yup.
> 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.
I think you may want some way for the front page ("cover") to reflect that this
is unofficial, or OpenSolaris documentation, with perhaps a clear disclaimer
saying Sun does not vouch for its accuracy, yadda, yadda, yadda. The typical
"your hair may fall out, dog run away," legalese.
> 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?
Well, that depends. :-) Do you think my 3 tiers have merit? If we stick to
just two, then I agree. If we have the 3, then I would see this
"OpenSolaris-style" documentation take maybe 60 or 70%, and the other 30-40%
being some blend of "Official Sun Documentation(tm)" and quick-n-dirty "here's
how it works/here's how to do it" notes. I imagine there to be some range of
variation within the "OpenSolaris" style, allowing it to be a little less
strict.
> Improving man pages may be another type that
> contributers can help with...
I see this as a really important one. Some of the man pages need...work... Some
are missing important details, clarity, etc.
> Would it help to
> have a section on content? For example,
>
> Recommended Content,
Depending on the topic, this may be easier or harder to do. Perhaps having a
"Suggested Material to Include" section may be worthwhile. Although, this does
not mean I disagree. I'm just not sure about the ability/knowledge of the
intended authors to address this.
> Sometimes I encounter documents that are little more
> than a reference of
> command line options, and leave all of the above to
> the imagination....
Been there, gae away the T-shirt. :-/
BTW, thanks for the comments. Gives me some more to chew on. :-) I'm still
learning how different people are envisaging this whole OpenSolaris.org thing,
and slowly finding a place in it.
Rainer
PS Sorry Michelle, I didn't get the time to read more of the Guide like I had
intended. :-( The weekend was fraught with detours and cul-de-sacs on the road
of life.
This message posted from opensolaris.org
