Re: issue #4 - tech.writing survey

[Dave Chisma & Gail Hodgson <chisma -at- C031 -dot- AONE -dot- NET -dot- AU>]

Jack Bonney wrote:

> this part of the recent survey for opinions and comments addresses the
> highly sensitive issue of "style"....

DC replies: Jack, it depends on what you mean by style. In this context,
I'll take style to mean a qualitative aspect of a work. Writers are
naturally concerned with style because style is an important reason that
writers (as opposed to typists) exist.

It would be a sad, boring world if everything looked the same (had the
same style). Every product on the shelf would work the same way, have
the same packaging, be presented in the same sizes and colours. Only the
contents would differ. In some fields of endeavor this is a good thing
(flight manuals, for example).

Many companies do have a corporate style that all writers are required
to follow. The main idea behind this is that once users learn how to use
one of the company's manuals, they know how to use all of the others.
Corporate style also helps to maintain consistency across a related
series of documents. Not only do corporate styles help to improve
usability of the manuals, they clearly identify them as belonging to a
particular company.

> most of the e-mail received rejected the notion that the manuals
> maintained by an organization should all have the "same look and feel";
> i.e. be organized, presented, formatted, produced, and revised to in a
> consistent manner over the lifetime of the document.

DC replies: I'm not surprised. One would have to very confident that
their style was perfect before committing to never changing it.

A better idea is to provide documentation guidelines. These guidelines
should be established only after exhaustive usability testing. Also,
this testing should be continuous, and the guidelines should be updated
as required. As technology advances, users start to expect more. You
have to make sure that you always satisfy (or exceed) their
expectations. If you don't do it, one of your competitors will.

Standards can be dangerous in that they can stop people from thinking of
ways to improve a product. If everything is already written in stone, no
suggestion you have will ever be considered. By providing guidelines
rather than very strict standards, your writers are working within a
framework that provides a certain level of consistency (very important
for usability). They're also working in an environment that means they
can think of ways to improve the style/process/whatever, and if their
ideas are good enough, they can be adopted across the
department/company. Stopping your writers from thinking creatively is
the perfect way of forcing them to produce bad manuals.

I believe owners and users like the idea that their documents won't
suddenly and expensively change for no apparent reason. However, I also
believe they would not want to lose out on benefitting from a useful
upgrade in functionality. I can envision changes to a manual's look and
feel that increases its funcionality.


> several writers rejected outright the concept of standardization - rather
> one person was outraged that such a thought would threaten his "art".

DC replies: Count me in. I think standardisation can be inappropriately
used.

Standardization is good in moderation. Consistency is important for the
usability of any document. It's not necessary to always use the same
font or paper size ... but you should always use structure you documents
in a consistent way, index them in a consistent way, refer to terms and
concepts in a consistent way, etc.

> we see "art" and standards in this work as being the difference between
> off-road rec. vehicles being driven by maniacs across the desert and lines
> on the road, signage, and proper training in driving habits and courtesy.

DC replies: What about multi-purpose vehicles used in an intelligent
manner for good, clean family fun off the beaten track? Life thrives on
differences and business runs on product differentiation.

Many businesses make products that must be supported with manuals.
Owners of these businesses look for ways to add value to their products.
One way is to produce better manuals than their competitors. Regardless
of the benefits of standardization, businesses will always seek to
improve and to offer something different.

People get satisfaction from doing something they can take pride in. By
taking away any control they have over the documents they produce,
you're taking away the joy and pride they get from their work. What you
seem to be suggesting is a perfect way to kill the souls of your writers
and guarantee that they produce sub-standard documentation. Give your
writers some control, and you'll be amazed by some of the innovation and
good ideas that they're capable of.


> several replies contained various approaches to writing a manual that
> included a step-by-step approach identified as a "methodology", and we
> agreed with most of them.
>
> however, there was not a single mention of a well-defined process or
> methodology for managing the entire publishing process  --  one that would
> reliably apply to any application by coordinating the 7 major tasks
> involved with this work, from authoring to revising/auditing the finished
> product sometime into the future.

DC replies: I'd be interested to know what you consider to be the 7
major tasks involved in producing user documentation. Maybe some of the
differences between your opinions and the results of your survey are due
to very different ideas of the documentation process.

> we expected to find a widely used approach to managing the entire process
> in such a way as to integrate the work with the tools and the people who
> use them -- nothing appears to available in this regard.
>
> we believe that this lack of defined publishing process contributes to an
> inability to delivery results of a pre-determined cost and quality.

DC replies: A process or methodology for managing the entire publishing
process can exist only in the context in which the process occurs.
Differences occur in products, resources, tools, customer needs, writing
environments, and so on. I believe the goal you seek is so generalized
as to be practically useless in the real world.

It's not hard to deliver results of a pre-determined cost and quality.
Simply pre-determine a high cost and an easily achievable (low) quality.
This is not 'inability' on the part of tech-writers, Jack, it's an
*avoidance*.

When you're documenting established policies and procedures, it's very
easy to plan and predict the entire process. (There's very little that
can change or go wrong.) However, when you're documenting something
unstable (like software while it's being developed), there are an
unlimited number potential problems and pitfalls. You can try to
identify as many of these as possible during planning, but you can't
guarantee any finished cost or quality for the documents. Luck plays a
very large role here! :-)

There was a problem with a product I was working on recently, when one
of our vendors went broke. We were planning our entire product around
being able to use one of their products. Our entire product had to be
redesigned, and at least 50% of what we'd done up to that stage had to
be thrown away. We still had to deliver the product on the original
date, so we all scrambled to get things done. In that instance, the
product we delivered cost more and was of lower quality than our
original plan. Having a vendor go broke wasn't one of the potential
problems we'd identified in our document plan! :-) **

Dave Chisma
chisma -at- c031 -dot- aone -dot- net -dot- au

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html