Tech Writers in Product Development - Follow up

["Hopkins, Sharon" <SharonH -at- CNRX -dot- COM>]

A little while ago I asked for input from the group on the role of TWs in
Product Development.  Many people contacted me asking that I share the
information I received.
Below is a summary of the replies that arrived from some of you who had been
through the process.  Thank you all for taking the time to reply and share
your wisdom.
Sharon Hopkins
CNRx

----------------------------------------------

Your "hidden agenda" is user advocacy, and you are the only one with that
agenda!

You know if it takes five pages to describe a function, that function is
four-and-a-half-pages too difficult for the end user to understand.  In my
experience, I have never found a UI design that couldn't be improved with
input from a TW.

----------------------------------------------

Congrats on the early participation.  I used to have that also in a
small "just post-startup" company  -  wish I hadn't left, but that's
another story.  If you weren't in Massachusetts, I would ask if you
needed another writer. :>

Anyway, I was able to give a lot of input into the design and GUI of
the application.  I essentially acted as a user advocate.  Programmers
have a tendency to believe "I wrote it this way and this is the way it
is going to work."  They also tend to forget that the majority of
users do not have the same level of computer expertise that they
themselves do.

This is not meant to bash programmers.  I have a great deal of respect
for them in general.  I simply wanted to point out that you can bring
a perspective that they usually do not have (i.e., that of the end
user).

The trick is to build a good relationship/rapport with the
programmers, especially the lead.  Make sure that your input does not
sound like a directive.  In particular make sure any criticism is
offered in a constructive manner because everyone is sensitive about
the work they produce, and programmers are no exception.  Most have
some personal stake in the code be it ego-driven or otherwise.

The best advice I can offer is the golden rule of do unto others as
you would have done onto you.  After all, you would not want them to
tell you how to write, you shouldn't tell them how to code, unless of
course you were a programmer in a previous life.

We also had a formal procedure that stated the user advocate had to
accept a window before it went into the end product.  We also had
defined GUI standards so it didn't seem as if our input was arbitrary.

I was able to make suggestions about workflow, screen design,
functionality, content, pretty much every aspect of application
development.  My input was not always taken but it was usually
considered to be worth listening to.

Call me or e-mail me at the address below if you want to hear more.  I
can wax poetic for you. :>

---------------------------------------------
I am currently working at a company where tech writing is developing the
documentation at the same time as the product is developed. A tech writer is

assigned to a team working on a specific application. A product manager
designs a draft interface and specification. The team comments on and
refines
the proposed design. This is where I get to have a lot of input into things
like
the names of windows, fields, etc. I also ask lots of questions about how
would
somebody use this? It helps that the application I'm working on is a
financial
application and I have a background in that area.

After the design is approved, I still get to make lots of input as the
coding is
happening because I am also developing the documentation. Mind you, this is
before I've ever seen the specific parts of the application working. I
develop from
the specification. While I am developing, I have to ask lots more questions
about how things are supposed to work. Many times these questions find
gotcha kind of stuff in the application.

After the coding and docs are done (on a build by build basis), I go back to
the
completed application and check my docs against the application to make sure

everything works the way I said it did. Testing also takes a look. I like
doing
development this way. It is, however, a lot more involved, but I think it
makes for
better software and better documentation.
---------------------------------------------

First of all, don't limit your input to the tech writing perspective.
You're in there as part of the product team and you should point out
anything you see that you think might improve the product. You might
be able to provide some valuable perspective, especially in the area
of user interaction. You have a little more distance than the
developers.

You should also think about how to document what's being talked about.
If there's a GUI and it's going to be hard to document, that could be
a good clue that it's designed poorly.

Finally, do some research so they don't have to go over basics for you
in the meeting, or be judicious about asking for background
explanations on everyone's time. If you can, take it off line if you
need to ask a question about technical basics.
----------------------------------------------

The biggest suggestion that I recommend is having a complete document
planning procedure in place. Your document plan needs to be a formal
signoff document that gets reviewed by you, the developer, the product
manager, and any one else in the organization whose input into the
documentation process you need (e.g., marketing, customer support,
etc.). Equally professional on your part is to request, as Product
Management did, input from other departments regarding your publication
processes and procedures. Your document plan should include a schedule,
worked carefully in cooperation with Product Management, that says when
your deliverables will be ready (1st draft, 1st tech review, 2nd tech
review, QA review, etc.).

Basically, what you've got is a golden opportunity to get product
management, development, and tech pubs all working together and agreeing
on when the "whole product" will be available--not just the code. In
older, more established companies, this type of thing is hard to
accomplish due to politics, departmental boundaries, and
"thats-not-your-job" syndrome.

I'd love to see what others have to say on the subject.
--------------------------------------------

I had such an opportunity in the early '90s on  a large program, in a large
division of a very large corporation. I sat in on all of the meetings aimed
toward developing the functional specifications for the product.

My most important input was to suggest opportunities to improve the human
interface in a way that would reduce the amount of user documentation,
training, and technical support. This was especially useful where functions
were similar to functions in earlier products and I could show large chunks
of documentation and technical support necessary to support those
functions.

In addition to the development engineers and myself, these meetings were
attended by people from technical support and marketing.

As is probably typical in large enterprises, engineering had more political
and financial clout than the support organizations, so the effect of our
participation as probably diminished; though, no doubt, valuable. In such
enterprises it is easy for the engineers to steer around difficult or
expensive design problems by believing they can be effectively solved by
documentation, training, and technical support. They are almost never right
when they make such decisions. Money spent "up front" is almost always
"money well spent."

In a small enterprise, your input can be really valuable and effective.

----------------------------------------------


As is always the case, the answers to your questions depend upon a number of
circumstances. There is a great deal of input that you can give upstream
that can add value to the development process.

If your team doesn't put together prototypes prior to coding, you can
suggest that they do so that you can review them. If your team puts together
prototypes of the program prior to coding, you can critic the interface
design before they have time invested in their code. Often technical
communicators find flaws in the flow of information that can be easily fixed
early on. Some other things to look at carefully are field labels (the
better the fields are labeled, the less online help need be written).

Look for ways to incorporate the instructions right on the interface itself.
Recently we have done this for a process that our users don't use very
often, and so they aren't likely to remember how to do it each time. We put
the instructions directly on the interface knowing that they would have had
to go to the help each time otherwise.

You can make recommendations for how error messages should read. Makes
suggestions on standards for the interface look and feel. I could go on for
the rest of the day as this is an issue very near and dear to my heart. I'm
envious of you folks who can move upstream like this. I think it will
improve your software greatly in ways you can't even imagine right now. Just
be confident. Your contributions will be very apparent to you after you
attend a few meetings. You'll find that your ideas will just flow. Good luck
and I hope I've helped a little.

----------------------------------------------------------------

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