TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Software documentation on the critical path From:"John David Hickey" <dave -at- toonboom -dot- com> To:"Techwr-L" <techwr-l -at- lists -dot- raycomm -dot- com>, "Pierre Roberge" <proberge -at- famictech -dot- com> Date:Tue, 19 Oct 1999 12:15:01 -0400
Greetings!
> I am a technical writer working for a software company. I write the user
What a coincidence! Me too! (what's wrong with me today... I'm so punchy!)
> This is no news to me, how can I document something
> that is not finished? I will complete my docs and helps at the same time
the software
> comes out of QA. Can I do better than that?
That's already an impressive accomplishment, but what if QA finds stuff that
needs to be corrected and these corrections affect your documentation? You
need time to adapt to that! You've got to find the features that will
change, find out how they change, recheck your index marks, and recheck the
entire manual to make sure these changes are reflected in every reference.
And the bigger the change, the longer this takes.
> coding. Is there another faster/better way to work? If the specs were
> frozen I could have finished the documentation before the developers
> finished coding but the specs are too vague and they change along the way.
The only thing that freezes in any company are budgets. I have yet to see a
company who can set a freeze date of the software and actually stick to it.
This is a hard-and-fast reality of software development. It ain't over until
the fat project manager screams.
> I have no choice to use the actual product to really know what it does and
> how it does it. Is it that hard to understand?
It's not hard for tech writers to understand, but it's a challenge for other
members of the team to understand since they don't really understand the
whole process.
My suggestion to you is that you need to write this whole process out and
show it to the people in charge, and slowly and patiently explain the
process to them. List everything you need to research, write, and check and
include the time this takes. This will show why you can't possibly have the
documentation ready at the same time as the software release, unless the
code freezes for two weeks before this date. Numbers don't lie.
It's not enough that tech writers need to be strong in the language they
write in, good with technology, good with people, experts in the tools they
use, and keep up-to-date on the latest technological advances. No no... We
also need to be tough and stubborn in the face of impossible demands and
challenges that would make Xena the Warrior Princess run for her Minister of
Parliment (or Congressman for you Yanks).
--
Be seeing you,
Dave
---------------------------------------------------
John David Hickey
Grand Poohbah of Documentation
ToonBoom Technologies
Montreal, Quebec, Canada eh?
pg: 514-205-9209
They say the pen is mightier than the sword.
But if you miss a deadline, you'd better bring the sword.
---------------------------------------------------
Don't confuse my opinions with my employer's.
Each exists in blissful ignorance of the other.
