Re: Challenges facing tech writers

[Elna Tymes <etymes -at- LTS -dot- COM>]

Kris Olberg wrote:

>  For entirely too long the
> community has lacked focus on the essence of where the community adds value:
> supplying content. Instead, we've made--or allowed others to make--tools and
> techniques our focus. All you need to do to verify this is to read any
> assortment of ads for technical writers. Review the skills requested--how
> many ads specify desired or required tools?

Most of them, frankly.  Unfortunately, there exists too few mechanisms for
evaluating content.  Submitting your manual to an STC competition, while
important for PR purposes (since most engineering managers and users haven't the
vaguest notion what STC is or does, but it looks good), doesn't establish your
content as "good" except by whatever standards the local STC evaluation team is
using this year.  One mechanism that DOES work is sale of third-party books,
except that this, too, is subject to bias - those introduced by the publishing
company's willingness to promote the book.

> * Redirecting focus from packaging to content. Attractive, easy to use
> formatting is important, but if the content is bad ...

Remember that people who BUY software are not necessarily the same ones who  USE
it.  In a large corporate environment, there may be a well-ordered process of
recommendations from actual users that results in a purchase decision, but in
most smaller business environments, those who purchase the software generally
have to make buy/don't buy decisions in a hurry, and that's where attractive
packaging plays an important part.

> * Directing focus back on the needs of the users. Cases in point of how we
> fail to serve our users' needs: <list snipped, but all good examples>

The real problem is that the engineering community has trained the users to
expect one-size-fits-all users' guides, and hasn't focused on just how people
learn a new tool.  Some people need a hand-holding document; some people want an
ad hoc approach, preferably online; some people actually need the time and
attention of a stand-up course instructor.  And there are other variations.
What usability studies have been done have largely focused on how people use
software, not the supporting documentation.  And most of us who have been doing
tech writing for a long time have lots of anecdotal evidence in support of this
point or that, but no systematic research.

> * Making it our responsibility to change our image. There is no doubt in my
> mind that corporate America does not perceive what we do as entirely
> positive. First, we need to stop puffing up into defensive positions and
> take a long, hard look at why this is so. Second, we need to take
> responsibility. Pointing fingers might feel good but accomplishes nothing.
> Nobody is going to fix this for us. Finally, we need to take action, both
> personally and as a community.

I agree with the first two points, but have a problem with the third, largely
because I doubt there is such a thing as a "community" of technical writers,
just as there is no "community" of programmers or engineers. Most of the time, I
can affect what I touch and the people who work for me can affect what they
touch, but beyond providing good examples, and moving from client to client
sewing the seeds of new perspectives, there isn't much individuals or small
groups can do.  Until we get groups of real users saying "Hey, this is good!"
we're going to be subject to the criticisms of engineering groups who have
mistaken notions about what users want, and to the criticisms from publicists
who ardently - but sometimes wrongly - believe that they're looking out for the
interests of the 'community' of great unwashed users.

Until we can point to statistically defensible studies involving the usability
of documentation and other learning tools, we're simply going to be talking
about our own, admittedly biased, experiences.

Elna Tymes
Los Trancos Systems


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=