G'Day All,
On Thu, May 22, 2008 at 04:31:23PM -0700, Ben Rockwood wrote:
> The OpenSolaris Style Guide is one of our important documents as authors
> which is descended from the internal Sun Style Guide. If you have not
> read it, please do so:
> http://www.opensolaris.org/os/community/documentation/doc_collab/style_guide/
>
> My question for us is, is the Style Guide relevant to docs today and/or
> is it relevant to all forms of documentation (blog, wiki, traditional
> manuals, white papers, etc)?
>
> I'd love to hear opinions on the style guide, whether you have read it
> and use it, and why.
I've read quite a lot of the style guide, and flicked through all of it.
It discourages me from creating documentation.
One of our main goals is to encourage the community to generate useful
documentation, usually unpaid. The most important opinions here are those
of our target audience - this community of volunteers.
I suspect that Ben Rockwood and myself would be among the top customers
in Sun's history who have contributed documentation, unpaid. So if you'd
like to know what the target audience thinks - asking Ben and me is a good
start. Several other names spring to mind too - but there aren't dozens
of us who have created and published lots of docs in the past, unpaid.
Here are my opinions on the style guide, not Sun opinions, but my opinions
as an OpenSolaris volunteer:
1) 270 pages is too long.
The Style Guide really isn't that important. It's certainly not 270 pages
important. I'd make it between 1 and 5 pages, as a condensed cheatsheet.
If you want me to study 270 pages before I'm allowed to write OpenSolaris
docs - then I'd expect a paid job in Sun's docs department. Is that the
message we are trying to send?
2) Content is more important than style.
I assume I don't need to explain why. Instead I suggest we spend more time
creating a "Content Guide", with has the Style Guide included as a 1-5 page
cheatsheet. The Content Guide will explain how to research and test
technical content, and which technical content is most important for which
audiences. It could contains several different types of documentation as
examples, annotated.
The first step towards the Content Guide would be creating a short list
of documentation examples. Here is an InfoDoc suggestion - it covers truss:
http://sunsolve.sun.com/search/document.do?assetkey=1-9-18674-1
This used to be public, I don't know why it's now closed.
3) Customers care more about accuracy and relevance than style.
I've spent a lot of time with many different customers, wading through
documentation to accomplish some task. I can't remember any of them
complaining seriously about style (even for unformatted InfoDocs). I do
remember lots of them complaining seriously about technical accuracy and
relevance. Given a choice, I believe customers would be happier with an
unstyled text file that was right, than a beautiful PDF that was wrong.
4) Technical Authors and Editors.
I like to write technical content. I don't like fussing about style, but
I'm not suggesting that style is unimportant, or that others don't like that
kind of work. If others took my raw technical content and improved the
style based on the Style Guide, then the documentation should be even better.
By saying that the Style Guide is important for all documentation is
suggesting that we all become both technical authors and style editors.
We should make it clear that this can work as two different roles.
If the medium is a wiki, then it is easy for this to be two or more
people - some who create the technical content (who are technical experts),
and others who improve the style (who are documentation experts).
5) The current state of documentation.
[Open]Solaris has a lot of great features, but not a lot of great
documentation to back it up. What are some practical ways for setting
up BSM auditing? BART? least privileges over LDAP? what about using
DTrace on a C++ application? how do we get IPQoS to work, really? what
patch manager am I supposed to use these days? ...
Not only is there a lot of features, but they are also moving targets -
keeping this documentation up to date is hard.
Right now, THAT is the most important purpose this community can serve -
to fill in the many gaps that exist as quickly as possible - not futzing
about style.
Here is an example:
http://www.solarisinternals.com/wiki/index.php/Zones_Resource_Controls
I wrote this (and the other Zones pages) years ago, but they are now
slipping out of date badly. What's more important - fixing their style,
or getting them up to date? I'm very, very busy on an internal project
right now - if I had 30 minutes spare to update that page - would you
rather I spent that futzing with style (or just reading the style guide),
or actually updating the content? I know what customers would prefer.
BTW: If you can help with that zones page, please do, it is on a wiki. :)
Brendan
--
Brendan
[CA, USA]
