Re: Do I have to understand the material?

["Doc" <doc -at- vertext -dot- org>]

Balderdash!!! I normally agree with much of your posting, but your constant
misinterpretation of single-source as technology rather than disciplined
content development is dwarfed by the assumptions you make below.

"Andrew Plato" <gilliankitty -at- yahoo -dot- com> wrote in message
news:165349 -at- techwr-l -dot-  -dot-  -dot- 

Introductory snip.

> 1. Do I have to understand the material I am documenting.
>
> Yes, if you want to be a good writer. The only way to write authorative
material
> is to have authorative knowledge.

... and if you're writing for an authoritative audience.

Ad hominem snip

> 2. What if I don't understand the material?
> Start learning, ASAP. Drop the processes, fonts, style guides, and one-off
"fun
> work" and start learning your employer's technologies & products.

No one should fool with fonts. That's what the style guide and style sheets
are for.
Use the process required or find another job.
"Fun work" seems to be a blanket condemnation of anything *you* don't think
is a valid activity.

What I really take exception to is your exhortation to learn your employer's
technologies.

Really? Are you going to sell your product only to the competition? They're
the only one's who would be interested in your employers code. Does the user
care if you understand the code? No! The user cares if you understand their
problems and their work methods and can explain to them how this product
will fit into their life. They do NOT want to understand the elegance of the
code, the problems overcome. All they want to do is get back to work.

The job of the tech writer is to let them do that, NOT to forcefeed them
technology.

Yes the tech writer should learn, but what we need to learn is what the user
needs to know.

> 3. But all I do is rearrange text, edit, and apply styles.
> You're not a writer. You're an editor. But, still knowing the content will
help
> you edit better.

I'll let this pass as given.

> 4. But isn't my ignorance a benefit, because I am more like an end-user?
>
> No. Ignorance is NEVER a benefit? In order to communicate to the end user,
you
> must know what information to communicate. You have to be able to pick the
> correct and relevant information out of the stack. You can't do that with
any
> degree of skill if you're content-ignorant.
>
> You're supposed to translate technical concepts into user-friendly text.
That
> means you have to understand thos technical concepts - so you can
translate them
> properly.

Maybe there are some people who rely on being able to read the code and
figure out what the programmer wants the user to do, but they didn't work
for me.

We don't pick information out of the stack. We find out what the user does,
how the user does it, maybe even why the user does it. Then we try to
duplicate it using the software or hardware. In other words we stand in for
the user, pre-testing the software and trying to fill in the gaps between
what the programmer did and what the user wants.

We are advocates for the programmer, nor for the code. We are advocates for
the product.

Our job is not to sell nor create interest, either. That's for sales and
marketing.

Our job is to keep the user using the product after they have spent their
money on it and after they have discovered that the programmers may know how
to program and design a glitzy interface but they don't know a damn thing
about the user's job.

Our job is to keep the product from becoming shelfware.

To do that we don't need to read code, we need to read user's, we need to
understand their jobs.

Many of the programs my group documented were for IT people, so we talked to
them rather than the programmers. Some years back I documented time and
billing programs. Should I have been interested in the fact that the
programmers could make the software sit up and do tricks? No! I was
interested in whether an accountant or lawyer who barely knew how to fire up
a word processor would be able to get their bills out without calling tech
support each month.

Programmers, for the most part, don't understand how the user will use the
product. If we become experts at the technology, we learn to use the
software the same way the programmers do because we can look under the hood
and go, "oh, that's what I need to do next." The user does not have that
same privilege. And furthermore they wouldn't want it if we gave it to them,
because it is not there job to understand the tool, it is their job to use
it.

I'll give you a case in point.

I work with a non-profit that takes surplus computers, reconfigures them
with Linux, KDE and freeware, then sends them to third-world countries to
community groups and entrepreneurs who are trying to start businesses.

Here's a section of a manual for a freeware spreadsheet program:
"1.2.2 a0 Mode
In a0 mode, relative references have the form col_let row_num, where col_let
is the letter of the column and row-num is the row number. col_let can be
upper or lower case. The cell in the leftmost uppermost corner is A1, and
the cell in the rightmost lowermost corner is CRXO65535. The columns are
initially single letters (A-Z) , then double letters (AA-ZZ), then triple
letters (AAA-ZZZ), and finally some quadruple letters (AAAA-CRXO).

B3 refers to the cell in the second column of row 3. Since this is a
relative reference, it will change when the containing cell is moved, to
refer to the cell at the same relative position; e.g., if the cell is moved
two columns to the right the reference will change to D3.

Absolute references have the form $col_let$row_num, as in $A$1 (top left
cell). These do not change when the containing cell is moved. Both types can
be mixed with predictable results, e.g., $A4 has an absolute column but a
relative row.

Ranges are given as cell_ref:cell_ref or cell_ref.cell_ref, where the
cell_refs describe diagonally opposite corners of the range. Thus, A1:B2
refers to the topmost, leftmost four cells in the spreadsheet."

I know what this means, probably you do too. But for the members of a
women's collective in Nigeria trying to set up a micro-loan facility, how
meaningful is it.

The writer of this end-user document understands the code and has documented
it completely. Is that person a technical writer? Sure, why not. Is the
documentation useful? Only to someone who knows how to read it.

If we choose this program as part of the configuration the documentation
will have to be rewritten.

Should we provide this documentation to an accountant here in the US? I
wouldn't.

Understanding the code and the technology does not make good user docs.
Understanding the user and how they will use the technology does.

> 5. But in my industry....
>
> Ignorance is not a benefit in ANY industry.

Ignorance is the norm in EVERY industry. If we were all experts we'd have no
job. There's a great book by Tom Holt, "Only Human" in which God has a
computer with no characters on the keyboard (because he's omniscient of
course) and the tech support technician for it has never received a call
(ditto).

>
> 6. How deeply must I know the information.
>
> As deeply as is possible. Its not a like you reach a certain point and
then shut
> down and stop learning. You should start out with basic, working knowledge
and
> then learn and absorb as much as you can over time. To do this
effectively, you
> need to learn some basics - like math, programming, or operating systems.
These
> basic concepts help you learn details faster and with greater effeciency
because
> you can understand related information.

You start this well but end in the same faulty premise, Technical writers
are not advocates for programmers, programming languages, math, or operating
systems UNLESS that is what the user needs.

> 7. But how can I ever be an expert at all this? I have so many other
things to
> do?

> Like what? Setup pointless processes? The core job of any writer is to
consume
> information, digest it, and then barf it back into a document.

Look, I don't have a lot of respect for people who flail around with
academic arguments about how you should do this and that either. OTOH I have
little respect for those who fail to take notice of useful information and
use it effectively. If processes are pointless, what about those that you
espouse? If someone is using something that you find makes your work more
effective, should you ignore it because it was published by the STC, ACM or
IEEE.

Content is king. I've said that before. Bad content is not improved by good
structure or flashy presentation, but conversely good content CAN be
diminished by poor structure.

You say that the core job is to consume information, digest it, and barf it
back. You left out some critical parts. You need to select food that is
appropriate for your chicks (that's baby birds, people, lighten up), and
you've got to aim for their beaks not just barf it uselessly on the ground.

> They just want information from documents.

They want information that applies to their job from documents.

> 8. But aren't writing skills important too?
>
> Yes, but not at the expense of content knowledge. You're half a technical
writer
> if all you can do is write. Remember, your profession has TWO components:
> TECHNICAL and WRITER. You can't eschew one in favor of the other.

Which is why I was finally persuaded, after many years of being proud of the
title, to consider dropping it. There are altogether too many technical
writers who continue to think of their job as writing technically rather
than translating it into user terms and into the user's frame of reference.

If you write documentation for an accounting program it is more important
that you understand accounting practice than C++. If you write IT
documentation, it is more useful to understand how IT works than it is to be
a whizz at Visual Basic.

Snip usual posturing.

Okay, I have to go to dinner now. The rant is over. I've doused the flames
coming out of my keyboard with the remnants of a four shot Americano, and
you may resume normal browsing at your leisure.

-Doc
---------------------------------------------------------------------------
David 'Doc' Lettvin
VerText
"Versatile Text for reusability and globalization"
http://www.vertext.org
vox: +1.978.468.1105
fax: +1.775.248.0508





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!
http://www.ehelp.com/techwr-l

TECHWR-L is supported by ads and sponsorships...and donations.
You can help maintain the TECHWR-L community with donations
at http://www.raycomm.com/techwhirl/abouttechwhirl/donate.html

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.