Technical writing in the development process? (take II)

[Geoff Hart <ghart -at- videotron -dot- ca>]

Melissa Nelson provided some additional info: <<This environment is 
quite different than the others I have worked in, and they have not had 
a full time technical writer, so we are all charting uncharted 
waters.>>

This is your opportunity to define the safe paths through those waters. 
Take the opportunity to make it clear that documentation is a 
deliverable like any other, and has dependencies. You can't describe 
something until it exists, whether as a tangible physical object, an 
onscreen image, or notes on a napkin during coffee break.

If the managers use project-management tools such as Gantt or Pert 
charts, they can add these dependencies to their charts and plan 
accordingly. In fact, it belatedly occurs to me that I don't see much 
talk about this in the technical communication community. I know that 
doc managers use these charts to plan documentation deliverables, and I 
assume development managers use similar tools. So perhaps we need to do 
a better job of learning the jargon related to these tools and thereby 
getting our names added to the list of dependencies.

<<I actually do get along really well with the programmers, I share my 
cube with three of them. However, we do most of our work for the 
military and they are much more concerned with showing the work to 
them, than to me.>>

Fair enough, but if I might be permitted a parable? I learned PageMaker 
in about an hour when I first decided to begin working with it. Was I 
some kind of software savant? Nope. Instead, I'd spent many more hours 
over the course of the year watching over the shoulders of our graphics 
people, and asking judicious questions when I didn't understand what 
was going on. With a little tact and sensitivity, you can learn an 
awful lot just by watching and unobtrusively asking questions at times 
when the interruption will be relatively painless... like when the 
person pauses to stretch, get coffee, or play with a toy.

<<I have been adviced by another techwhirler to come up with a doc plan 
for each new project, which I think will help let everyone involved 
know when I need to be involved.>>

Good plan. Just don't forget to put in the good word about "design 
thrice, program once". There's lots of good stuff out there (most 
recently and most notably by Alan Cooper, a respected programmer) about 
how and why this works. Check out "The Inmates are Running the Asylum" 
for details. And spread the message that feature creep is bad for 
business because it prevents you from selling those features as an 
upgrade.

<<It is nearly impossible for me to be involved in the beginnings of 
our military projects as most of those meetings take place on a 
security level that is well above mine. That is always another fine 
line I need to walk.>>

One obvious solution is to obtain sufficient clearance to participate 
at an appropriate level. But the more important issue is to remember 
that if you've got the clearance to see and ask questions about and 
document the final product, you've got all the clearance that you 
really need. Do you know what the difference is between a lecturer and 
a teacher? The teacher engages in dialogue. Communication goes both 
ways in a dialogue, and that's what you need to remember when you 
interact with them. You need to have the right to ask questions and 
receive answers, not just take what is handed to you.

<<As for the downtime, I need to figure out just how generous I should 
be with my time as far as non-tehnical writing projects.>>

An important clarification to what I said earlier: I am not suggesting 
that you become the staff cook or janitor in the early stages of the 
project. I'm only suggesting that you use some of your spare time for 
building relationships and gathering intelligence about what's going 
on. As the product becomes increasingly solid, you'll have less free 
time because you'll be spending more time planning (e.g., writing 
outlines and feature lists) and actually writing.

<<I hate being bored so I will jump into help where I can and then I 
end up with conflicts that way. I have gotten a little better at that, 
with offering to help my PM first and foremost, that way he is aware of 
all the conflicts.>>

Time management is definitely something of an art. One helpful solution 
while you learn that art is to focus on your needs first. Prepare your 
outlines, gather your source materials, make lists of unanswered 
questions, and so on. Then in the "I have nothing reasonable I could be 
doing" time that remains (probably less than you'd expect), you have 
time for the peripheral things like attending meetings to keep abreast 
of what's going on.

<<On an upnote I have become really good at doing screenshots and 
powerpoints for my PM of functions that do not yet exist.>>

"Writing documentation is just like writing science fiction; we both 
write about things we imagine will happen sometime in the 
future."--Susan W. Gallagher <g>

But your point is a good one: during quiet times, learn to master your 
tools. When the crunch arrives, you'll be so good at using those tools 
that you can ignore the tools and focus on the actual work. Tools are 
just a means to an end; they shouldn't be an end in themselves.

Speaking of tools, use your downtime to prepare a kickass template for 
the final documentation, to prepare a list of index keywords and 
synonyms (so you can edit this after it's had time to sit and ferment 
and so the list will be ready when it comes time to index the docs), to 
create and test an overall navigational structure, and so on. Come up 
with checklists for consistency (both style and content), and begin 
constructing a style guide. Etc. I'm sure others will have other 
points.

<<I am hoping that by getting involved in doing powerpoints of 
functions that will (hopefully) exist in the future, I will be a little 
more prepared for when they are developed.>>

One advantage of being the person who records the minutes at a meeting 
is that you get to choose what to record. Now please be clear about 
this: I'm not suggesting that you deliberately distort the truth. Apart 
from the ethical considerations, you'll lose all credibility when (as 
is inevitable) you're caught. But putting things down in writing means 
that you have a record of what was said, and as the recorder, you're 
the one who gets to say "So let's confirm that we all agree on this: 
Feature X will have an interface freeze tomorrow, right?"

If anyone wants to change things, then it's their responsibility to 
prove to you that they told you about the change. You can't be held 
responsible for things you weren't aware of, particularly when you make 
ongoing efforts to remain aware. Ditto for functions being described in 
PowerPoint: If there's no design document, these presentations become 
one. Apart from giving you a chance to nail down details and resolve 
problems when you work with a developer to produce these presentations, 
it's human nature to stick to the design once it's been carved in stone 
(or PowerPoint, in this case). Of course, some people also completely 
ignore these designs, but some won't, and for every one that doesn't, 
you've got a solid target you can write about.

Plus, many developers will hate doing this work, and by becoming an ace 
at doing it, you can demonstrate to them how much time they'll save by 
working with you instead of doing the work more slowly themselves.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content 
delivery. Try it today!. http://www.webworks.com/techwr-l 

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.