Technical writing in the development process? (take II)

Subject: Technical writing in the development process? (take II)
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Melissa Nelson <melmis36 -at- hotmail -dot- com>
Date: Sun, 25 Jun 2006 11:01:58 -0400

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)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

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

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 for more resources and info.


RE: Technical writing in the development process?: From: Melissa Nelson

Previous by Author: Technical writing in the development process?
Next by Author: Technical writing in the development process?
Previous by Thread: RE: Technical writing in the development process?
Next by Thread: Re: Technical writing in the development process? (take II)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads