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]
