RE: where do docs fit in the development process?

[KMcLauchlan -at- chrysalis-its -dot- com]

Susie P.,

We are roughly your size, and we sell hardware and 
software, for which we make SDKs *and* end-user stuff, 
so I (as lone writer) deal with docs for both.

With one or two (best forgotten...) excursions, I 
have been part of our Product Verification (PV) 
department. This is a very happy arrangement. I 
have a natural "in" during the early stages of a 
project, as our PV team gets invited to participate 
soon after the "I just had a great idea!" stage.  :-)

We do have product line managers for our products 
and projects, and they get to write up the specs. 
The specs include customer dodumentation requirements.
The PV manager and I review and modify those specs, 
in co-operation with the originator. The person who 
handles creation and management of our Bills of Material 
(BoMs) also works for the PV manager. So that's 
another check and balance on "what documentation 
goes with which project".

The spec documents are not huge things. They have 
just enough detail to convey the requirements. 
They often refer to previous product specs and 
list just the changes and additions, as well as 
prioritizing all requirements and identifying all 
"issues" from previous releases that must be 
fixed/addressed for the coming release. Often, 
those have already BEEN addressed in the interim, 
but putting them in the spec ensures tracking 
and closure.

I just recently finished a release, in which we 
ran a "documentation improvement" project with 
our Customer Support group. Everybody is happy 
with how that turned out. I was amazed... rather 
than each individually review a doc and hand me 
a marked-up copy, they did their reviews, did 
their mark-ups, then met with the Product Manager 
and mushed it all together into one (relatively) 
cohesive "suggested" document.  I then met with 
them and we very quickly dealt with just that one 
doc (this was for install and setup... we'll do 
the config and integration doc for that product 
another time).  I implemented the revised version 
and put in the relevant detail for the new product 
release, and everybody is happy.  Worked out 
really well.  What a bunch!  :-)

Of course, I get a lot of other requests for little 
doc-lets.... one-page Tech Notes, special-purpose 
thingies, edits of other people's stuff, etc.
My standard reaction is "Sounds good. Why don't 
you put that in an e-mail, and CC: Diane (the PV 
manager)?"

In fact, I don't accept purely verbal requests. 
If it's from somebody at the top, then *I* write 
the e-mail, saying: "Is this what you meant?"
And I don't act until I get confirmation that 
the requester and I agree on what, exactly is 
wanted.

When I get something via e-mail, I always ask 
the necessary questions to nail down the scope 
and the hoped-for delivery date (which could 
very well be "tomorrow morning"). By keeping it 
all in writing, we ensure that:

a) we all agree on what is wanted

b) my boss(es) know what's on my plate and 
   can intercede to negotiate any re-scheduling 
   that might become necessary

c) nothing gets forgotten, with two or more 
   people involved in the scheduling and the 
   follow-up.

Whenever there's a conflict over "resource 
availability"... me... I haul the two 
(or more) conflicting parties into one room 
and let them negotiate. (At one time, that 
meant "If you want your stuff, be at the 
meeting", but these days, they're all so 
reasonable that THEY usually call the meetings 
and get each other to attend, just to keep 
things rolling smoothly... we're all very 
committed since watching more than 100 of 
our compadres get the door last summer... :-)

In those little meetings, I just tell them 
what's possible, or likely, and they do the 
shuffling and dancing among themselves. If 
there's any lingering friction, I haul Diane 
into the fray as my not-so-secret-weapon. 
It's not that she's so much better than I at 
getting other folks to agree on the best use 
of me, but she also has the perspective of 
what PV resources are available, and that can 
be the deciding factor in many disputes.

Finally, with respect to *WHEN* I do the work 
for the major projects, well it often (but not 
always) works roughly like this:

1) get alerted and maybe participate in some 
   early meetings as the project is getting 
   off the ground;

2) keep an ear to the ground, and watch for 
   any revisions of the spec(s) throughout 
   early development;

3) get involved in any demonstrations and the 
   alpha product;

4) prepare existing docs for revision, or write 
   the framework of new docs;

5) let it sit for a bit;

6) when product begins to gel, work like a dog to get 
   some roughly finished docs ready for Beta;

7) live in the pockets of the relevant PV testers 
   to get the "final poop" into the docs (including 
   whatever remarks come back from Beta),

8) implement and close any "RAZOR" (old bug-tracking 
   system) issues or any "Clearcase" (new bug-tracking 
   system) issues that have a documentation aspect;

9) have PV testers review their respective sections 
   of each doc and wrap up any and all suggestions/
   comments from them.

Steps 7, 8, and 9 take place in the final few days 
or couple of weeks (depending on size of project), 
and are when most of the obviously productive doc 
work gets done. What you don't see is what goes on 
in my head during the time that info is just 
percolating around up there...  :-:

SDK stuff is usually quite solid, well before the 
final stages of a release. It tends to be the user 
stuff and install stuff and cosmetic stuff that keeps 
getting tweaked.

What we normally do is produce "Release Candidate" 
builds and CDs that have everything in place except 
the documents. Then PV and I beat on the software 
and drivers. I do the final tweaks to the docs, we 
find any glitches or work-arounds for stuff that 
isn't going to be fixed before final release, and 
then my docs get signed off. A last release candidate 
is made, WITH the docs as the ONLY change, and a 
quick test is done to see if adding the docs has 
broken anything.   Out it goes, usually the next 
morning.

THEN, I do the Release Notes, and make them available 
on our web site. They don't go on the CD. THAT decision 
took quite a load off me at release time, I must say.

HTH

/kevin

> -----Original Message-----
> From: Susie Pearson [mailto:spearson -at- espial -dot- com]

> I was just wondering where documentation fits into the 
> development cycle
> where you work.  How is a documentation project initiated?  Is there a
> process, or does somebody tap you on your shoulder and say 
> "Hey, I need
> this"  

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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