Re: FWD: Appealing to or introducing Tech Comm "best practices"

Subject: Re: FWD: Appealing to or introducing Tech Comm "best practices"
From: "Eric J. Ray" <ejray -at- raycomm -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 24 Oct 1999 13:14:26 -0600

> As a technical communicator in the software industry, I rely heavily on
> resources such as this listserv, STC and ACM SIGDOC publications, books by
> tech writing gurus (JoAnn Hackos, William Horton, Karen Schriver), etc. to
> make sure I'm on the right track and not missing out on better ways to
> create documentation.

In principle, that's well and good, but experience can also be a good teacher
and a great bellwether to determine if you're on the right track as well.
Not casting aspirations on any of the sources you mention (particularly Karen,
who thoroughly documents her books with extensive bibliographies), but
just because it's in a book doesn't mean it's right, just because it's
published doesn't mean it's right, and just because it's conventional
wisdom doesn't mean it's right. (Right in this case means anything from
"correct" to "appropriate for your situation".)

For example, I like Bill Horton's books, have most of them
(if not all of them), and use them regularly. That said, I've yet to
see much empirical evidence that he's _RIGHT_ as opposed to simply
rational and thoughtful (which is still worth a lot, but hardly makes
Horton's opinion definitive).

Published AND peer reviewed is a step in the right direction, but still
definitive by no means.

To return to your specific point, perhaps your colleagues are writing
documentation that's printed in 14pt Courier type on 8 1/2 x 11 paper.
You think "other typefaces etc. are far more readable, and so-and-so
says that software docs should be in 8.5 x 5.5 books", but do you know
why the current standards are as they are? Has anyone done a study?
Has anyone asked the users? Three reasons I could think of right off
to NOT follow these "best practices" are because 1) users _think_ that
14pt courier is more usable, and user opinions have a direct impact
on your software sales or 2) an empirical study shows this format to
be particularly usable for your readers or 3) your readers are change
averse and vocal.

> But I keep running into technical communicators who, generally because
> they "fell into" the field, have no knowledge of these resources and who seem
> to prefer to make up their profession and their documents as they go. While
> these folks are plenty smart, mean well, and have expertise to share,
> their documents often show a lack of exposure to the "standards" or "best
> practices" of the field. (Not that any two tech writers could ever
> completely agree on what the standards are, but there is at least some
> consensus on some issues.) Also, maybe because these tech writers invented
> their work without help from outside sources, they feel great ownership of
> their work and can be highly defensive toward suggestions for improvement.

Depending on what you mean by this, I either agree or disagree. ;-)
Several people seem to have interpreted this as you saying that you
know more than your colleagues and you think you need to bring them
to the light. However, the first couple of times I read it, I saw it
as a legitimate observation that many documentation products are as
they are simply because "that's how we've always done it", and that's
not always a good thing.

From what I've seen, there's darn little consensus on most non-trivial
issues, and where there is consensus, it often exhibits a disconnect
from reality.

> Does anybody out there have thoughts or advice on how to build a good
> working relationship with such a colleague, while also encouraging them to
> open up to the standards and best practices of the field, as described and
> discussed in the major resources of the field (STC and ACM pubs, TECHWR-L,
> etc.)?

Well, the first thing I'd suggest is (following in the lead of several
other posters) to produce work that's demonstrably better than that of your
colleagues, based on your knowledge of "best practices". That said,
before you deviate too far from what's being done currently, be darn sure that
you know the full scoop on what's being done and why. Lots of people
and companies (myself included) do stuff that's really stupid, both
on the surface and on second glance. However, if you know the full
story, you'll either understand or accept the "stupidity" as a fact
of life.

Second, as you've undoubtedly learned from this list already, you can lead
people far further in your chosen direction by simply sharing what works
for you and why, rather than by telling them that they're misguided or
in need of professional help (in the form of STC, ACM, or Bill Horton).

Second, I'm an inveterate forwarder-of-good-stuff. (No, not jokes etc.,
except to a select few, but rather substantive stuff from the likes of
Jakob Nielsen, this list, or other sources.) For example, I'm in the
middle of reading an article about online information usability that
I'll probably forward to a number of people. It might or might not
actually change anything, but it'll help share the wealth on what empirical
research is available on this topic.

In general, when it comes to "encouraging people to open up", that can
be perceived as "tutoring and mentoring" or "rebuilding in your own
image"...only you know what you intend. One is far more successful, in
general, than the other.


Previous by Author: Re: Newbie Blues
Next by Author: Re: John Galt: Lover of Standards
Previous by Thread: RE: Appealing to or introducing Tech Comm "best practices"
Next by Thread: Re: Appealing to or introducing Tech Comm "best practices"

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

Sponsored Ads