Re: Style guides

Subject: Re: Style guides
From: Yves JEAUROND <jingting -at- rogers -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 13 Apr 2007 09:37:38 -0400 (EDT)

Rob Hudson:

These are all excellent suggestions. I would add that with
illustration (screen grabs, charts, graphs...) becoming so
commonplace in TW, and if you are designing style guides for clients,
you can get some 'visual' style guidelines from:

(1) Robin Williams, _The Non-Designer's Design Book_, Peachpit Press.
Contrast, repetition, alignment and proximity are discussed in a fun
and informative way. Ties in nicely with the "parallelism" entry in
Microsoft's _Manual of Style_.

(2) _The Chicago Manual of Style_. When Microsoft's
_Manual of Style_ came out in 1995, it was outstanding
as a checklist of necessary terms to be investigated further.
When style issues beyond its scope would crop up, Microsoft
recommended _The Chicago..._, for tables, lists, indexing, pagination,
and so on. Higly recommended if you have to design
any of these elements in a document.

(3) Speaking of elements, (and please don't laugh :-) Euclid's
_Element's of Geometry_ (circa 400 B.C.) remains one of
the earliest samples of great TW. Euclid included illustrations,
cross-references, definitions, procedures, and so on in his _Elements_.
Better to get a version with little or no commentary, like the one in
the set of Britannica Great Books. On the web, the commentary
can be a useless distraction:

(4) Edward Tufte, _The Visual Display of Quantitative Information_
has good advice on the semantics, syntax and usage of
charts and graphs, often included in TW.

For usage
Obvious, often neglected: a respectable, general dictionary (!)
like the OED or Webster's has answers to usage for things
like "click" vs. "click on"--clients find it comforting to find out
that it is more of a language issue than a technical issue;
people were clicking their heels long before mice. :-)

And there's an "artsy", opinionated, controversial, checklist
of laymen's usage for technical terms in Hale's _Wired Style_,
sub-titled: "Principles of English Usage in the Digital Age".


Yves Jeaurond
-- Writers find solace in Northrop Frye's _The Educated Imagination_ (1963) --

Stuart Burnfield <slb -at- westnet -dot- com -dot- au> a écrit :
"IBM Style provides consistency guidelines for IBM information.
The guidelines cover all areas of the business: hardware, software,
mainframe, workstation, and more. These guidelines are developed and
maintained by a committee of technical editors from each IBM Division
around the world who ensure that the guidelines address a global
audience that uses a wide range of IBM products."

You can download a copy from:

The general IBM 'Ease of Use' portal, containing other style guides,
downloads and resources, is at:

One other reference you might find useful: a book called Developing
Quality Technical Information.

It was written by a group of writers and editors at IBM. They're mostly
the people who maintain the IBM Style guide and Word Usage DB, so the
book complements the online resources nicely. In fact, the in-house
version of IBM Style has a reference at the bottom of each topic to the
corresponding section in DQTI.

Sun's "Read Me First! A Style Guide for the Computer Industry" is an
excellent short guide to the most common questions and problems faced by
working tech writers. I haven't seen the second edition but I assume
it's like the first edition, only better.




Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Re: Style guides: From: Stuart Burnfield

Previous by Author: RE: no QA
Next by Author: Anthropomorphism [was RE Table punctuation]
Previous by Thread: Re: Style guides
Next by Thread: RE: Style guides

What this post helpful? Share it with friends and colleagues:

Sponsored Ads