Re: Occupational hazard of techie tech writers

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

> Hello Colleagues,
>
        <snip>

> Anyone who is really into technology, and who becomes a technical writer,
> has advantages and one big occupational hazard:
>
> Advantages:
>
> * ability to understand complex systems
> * ability to learn how to use the functionality  of new software even when
> parts of specs are missing
> * ability to analyze a system and reduce it to its basic concepts
> * ability to compare totally new methods or functions to existing
> languages,
> protocols, systems
>
> Occupational hazard:
>
> * inability to explain software or functionality to a beginner (sometimes
> even the inability to realize that you NEED to explain the software to a
> beginner)
>
        <snip>

        IMO, this is the old "a person cannot be technical and creative"
stereotype rearing its head again.  People, listen.  The term "Technical
Writer" is not an oxymoron.  Being technical and being a writer is indeed
possible!  Do I have to bring out the Mike Wing Technical Writing Skills
matrix again?

> Nowadays, no one is teaching every user of advanced software the
> needed subjects (for example, basic programming concepts, true
> object-oriented programming, principles of SGML, even TCP/IP).
>
        This is true and not true.  I think we need to make a distinction
about types of software writing.  Again, it depends on audience.

        Most software writers really are not software writers.  They are
software applications writer.  That is they describe the interfaces, order
of operations, and results of running the software.  Their audience is
software users.  Their audience is not so much interested in the logic,
code, and programming of the software as they are using the software to
achieve desired results.

        A software writer (as opposed to a software application) writer,
describes code logic, interactions between software modules, writes/analyzes
example code, provides software customization instructions (such as
automation syntax), describes network configurations, and so forth.  This
writer's audience is not necessarily using the software to produce a
product.  Instead, they may be customizing and configuring the software
application or building a new application from the software (such as
building on an API or toolkit).

        As an example, the company I work for produces software for
generating maps.  We have software application and software writing these
products.  The software application writers produce user guides.  Because
the audience consists of cartographers; surveyors; utility, transportation,
and civil engineers (to name some), it is advantageous for the software
application writer to present the material as to how the software can be
used to detail escarpments, provide shortest routes, etc.  Having some
cartography, geography, and related sciences background is a great plus for
this type of writing.

        Some of the software also requires software writing.  I produce API
documentation, automation code examples, interactive programming guides, and
so forth that help the user build on and/or customize the application.  I
don't need to bother with GUIs, user workflow, and results on the map.
Because of my audience, I need to work with programming logic, sequence, and
syntax.  I also have to work with compatibility between network software,
module interoperability, and system configuration.  I have some programming,
internet, and electrical engineering background which is a great plus for
this type of writing.

> We're told we can assume a certain level of knowledge, but unfortunately,
> every one of our users is going to have forgotten some of the basic
> concepts
> necessary to use any advanced software. And each person's forgotten
> concepts
> are different from another's. Therefore, we have to include those concepts
> somewhere in our documentation. <snip>
>
        Again this is audience.  If they are software users, I disagree.  If
they software programmers or administrators, I agree.

> Therefore, there's a problem. Any brilliant technical writer who's into
> technology and hasn't done a lot of technical writing is going to produce,
> as a first draft of a first project, a document that will fail usability
> testing.
>
        Do you know this for sure??  I would suspect most writer's first
drafts will fail usability.  Especially if they "haven't done a lot of
technical writing".  This is just a continuation of the stereotype that
"that technical knowledge overwrites the part of the brain used for
creativity" or vice versa.

> How can we avoid this situation?
> ...or even correct it once it happens?
>
        Experience -- whether the writer is technical or not.

> - Carl Stieren
>
>
Mike Wing

Michael Wing (mailto:mjwing -at- ingr -dot- com)
Staff Writer
Intergraph Corporation; Huntsville, Alabama
http://maps.intergraph.com


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