atw: Re: Style guide: keep it short
- From: Janice Gelb <Janice.Gelb@xxxxxxx>
- To: austechwriter@xxxxxxxxxxxxx
- Date: Wed, 17 Sep 2008 07:17:10 +1000
Stuart Burnfield wrote:
The style guide I'd like to write would be hundreds of pages long. The
style guide I expect other people to *use* had better not be longer than
about six A4 pages (if printed out; actually it would probably be one
long HTML page with links).
[snip]
But how could you possibly distill a lifetime's wisdom and experience in
under a thousand pages?
1. Don't try. If you can think of fifty short, worthwhile, guidelines
and you can get people to consistently follow ten of them, you're doing
well.
2. The fine folks at Sun Technical Publications, Macquarie, the AGPS,
and so on, already wrote the thousand pages and more, and they did a
good job. Stand on their broad shoulders, not their toes.
I'm afraid I have to disagree with you about how possible
it is to distill a corporate style guide into 50 guidelines.
The style guide from Sun that you compliment was largely
based on our internal style guide, although it was made
generic and some content was added for a third-party
audience. However, other content that was specific to our
internal audience was deleted, so the size was approximately
the same. Contractors and new writers are usually really
pleased to find a comprehensive document that they can use
as a reference to get up to speed with our house style, and
to find out how to increase their skill level for indexing,
for example.
For a large company with writers who are not directly
in contact with each other or with staff editors, and
with the trend toward engineers and other non-technical
communicators posting product information directly onto
wikis, blogs, and so on, I think the need for a
comprehensive style guide cannot be overstated. As long
as the material is indexed well and is searchable online,
and as long as it is specific to your audience (e.g., not
reproducing extensive grammar or other generic guidelines
that are available elsewhere), I don't think length is
that much of an issue.
I've certainly advised in presentations on developing a
style guide that if you have limited resources to
develop one, you could use something like _Read Me First_
and just add your own specifics or exceptions. However,
note that this doesn't mean that a comprehensive style
guide could be 50 guidelines long - it just means that
you've got a style guide consisting of the 300+ pages
of RMF *plus* your own 50 guidelines.
>
3. Leave out your pet peeves--every one of them. Nobody cares.
Hey, my pet peeves have been developed over years of
screaming at unclear documentation!
-- Janice
***********************************************************
Janice Gelb | The only connection Sun has with
janice.gelb@xxxxxxx | this message is the return address
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter
To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes) go
to www.freelists.org/list/austechwriter
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx
**************************************************
Other related posts:
