Re: 'Old fashioned' Tech Writers

[keilanhoo -at- yahoo -dot- com]

> > You still have to match the
> > granularity and the coverage to the anticipated skill level of the
> > audience, and that is still a variable.
> 
> No, it's not a variable. The product you are documenting has a target
> audience, and that target audience has a recommended skillset. You
> write to that. You can't chase the lowest common denominator; 
> 


It is a variable for someone who has to document more than one thing. The
audience is variable at the project level. If you always write the same
kind of thing aimed at the same type of audience you can assume a certain
baseline skillset. But when you write about more than one product, when
you write for different customers, your audience can and does change.

I don't chase anything; I write as required by the contracts.



> > Technical writing is not always for a technical audience. What about a
> > person who has just bought a computer for the first time? What about
> > people who are trying to learn how to use something like Photoshop for the
> > first time? There are some still out there, more than we'd like to think.
> 
> If that is your target then write for them. Otherwise you need to
> write for your audience.

That's *my* point. And since the nature of the audience changes depending
on the nature of the product you're documenting, then from project to
project the audience skill level very definitely is variable.


> 
> > I just finished doing a software user guide for a customer who is buying
> > our product for use by employees who had never used personal computers
> > before. Up until this very year they had done all their work on old
> > green-screen dumb terminals. I had to design and write the manual on the
> > assumptions that the users had never before worked on a system that
> > included a mouse. (In computers, what the heck is the plural of "mouse"?)
> > I had to put in an annex that explains, in excrutiating detail, how to use
> > a mouse, what a pull-down menu is, how to scroll, etc. It is a real
> > challenge to write a software user guide for people who may not know what
> > the word "click" means.
> 
> I sympathize but I recommend you not document what isn't your product.
> If the purchase of your product came with these new computers (that
> is, you sold them the computers as well) then I can see an exception
> to the rule, but ideally you should never document someone else's
> technology in your product's documentation. It can potentially cause
> more problems than it'd fix.
>

I already know that. But my boss tells me "make sure it includes
rock-bottom-level instructions on how to use a mouse because that's what
the customer wants." Am I supposed to tell him no? On this project I did
make the argument that it would be inefficient to reinvent the wheel. I
pointed out that there are already sources that could provide the end
users the kind of basic information they needed, and that those sources
were polished to a degree that I could not match with the time and
resources available to me. And I was told the customer just wanted another
chapter to the user guide, and to just do it.

My point in writing that paragraph was to point out that yes there still
are people who need to be told what "drag and drop" means.



> 
> > The UI designer can put popup tips all over the interface
> > to explain every feature on it; in most applications, that still does not
> > tell the user *what to do next*. 
> 
> I think you're missing the point of what a UI designer does.
>

I'm addressing one aspect of what a UI designer can do. I'm pointing out
that procedural information can't be built into the UI by using nothing
but tool tips or similar methods.


 
> > It does not give the user who needs
> > information about a procedure a way to find procedural information.
> > Creating help that addresses those types of concerns is still enough of a
> > chore that you can't do that and design/write/debug the interface at the
> > same time.
> 

> Well, I disagree. If the UI is properly designed, the task of the
> technical writer for UI instruction becomes easier. Now, I wouldn't
> say that the same UI designer should also be responsible for
> documenting the API behind the UI or anything. But how is a UI
> designer who also documents the UI any different than the programmer
> who documents their code? [insert your joke here about programmers
> writing documentation] We expect our programmers to document their
> code - it's not "code complete" without it.
> 

Maybe easier. But the fact is that writing and debugging the actual UI,
and creating the user guidance on how to do things, is simply too much
work for one person under normal development schedules. If you have one
programmer trying to do all those things you have to extend the schedule,
or, in order to keep to normal schedules, you'll have to divide the
functions and have multiple people do the project. Yes they'd have to work
closely together, but there's still simply too many keystrokes to be made
by one person.

What do you mean by "documents their code"? Every other time I've heard
that it's meant applying internal comments in the code. That is not
documentation as I consider it. That's meant as guideposts to other
programmers to clarify a particular usage of a method, or to locate a
specific branch point, or something like that. That is definitely not the
same as trying to write a document that explains the coding rules or the
design philosophy. And it sure isn't the same as trying to write a
task-level manual that explains how to work thorugh the UI to perform the
tasks the end user cares about. To use an analogy, commenting the code is
like putting a timing mark on the crankshaft pulley - it is not the same
as writing a tuneup procedure manual. (That analogy probably makes me
sound like a dinosaur but what the heck. :-)

If you mean having the programmers actually write API docs and reference
manuals and such - I wish I could joke about programmers writing
documentation. I've been a technical writer for almost two decades and
every example of programmer-generated documents I've ever seen has been
painful to read. It doesn't mean they aren't as bright as tech writers -
it just illustrates what I said about the time requirements. Most
programmer-generated documents are the way they are because the
programmers just don't have the time to become good both at code crunching
and writing.


> > I'm sure companies who want to cut their payrolls will try fusing the
> > jobs. And eventually they will come full circle back to the discovery that
> > created the position of techical writer in the first place - developers
> > don't have the time to create products and document them both, even if
> > they have the language skills.
> 
> I suggest not using a "all or nothing" perspective.

This is betting on human nature. There are still a lot of programmers who
are not good at telling other people how to use the product they turn out,
or even explaining how it works. And there's still time enough in the day
to make only so many keystrokes. Considering the fact that the "death
march" seems to have become the norm in software development, I'm pretty
sure the realization I wrote about will come fairly soon.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.