RE: where do docs fit in the development process?

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

"Susie Pearson" <spearson -at- espial -dot- com> 

> OK -- so how am I supposed to be finished documenting at the exact time
they
> are finished working on the SDK?  That is where I'm having a problem. 
No
> one tells me about changes, and when I'm juggling 3+ products, I don't
> always have time to approach every single engineer to ask them what has
> changed.

This is why you need to understand the product and technology inside and
out. You should be working AHEAD of the engineers. Documenting stuff
before they even coded it. Its not insane if you understand what they are
doing and you have an established relationship with the engineers. 


> Another problem is that the engineers are working madly to meet
> their RC deliverables -- they don't always have the time to hold my hand
> through every change. 

Nor should they. You should be able to handle those issues and only be
approaching the engineers for clarification or "out of the ordinary"
issues. 

> This is why I think there should be my docs should be
> staggered after the product is RC -- then they should both go to QC.  So
> that I can check my docs against a stable product, and so the engineers
have
> time to sit down with me and answer questions.

Generally, RC product also demands an RC document. As the product is
tweaked and repaired through beta cycles, so is the document. I don't
think it is strange or unusual to ask for a final draft at RC1.  

> I'm not asking for a rigid process -- just something to make things a
little
> easier.  So you think the last-minute "hey, can you have this done by
2pm"
> approach is fine at 1pm?  Sorry, but I have a million things on the go
at
> any given time, and I think there *must* be a better way of doing
things.  

There is - you need to develop a better working relationship with your
engineering staff. 

> Sadly, the manager are rarely available for meetings about docs -- they
> always seem to be in meetings with each other, contemplating the size,
shape
> and color of each others' belly button lint.  

That's because you (and this is your job) have not made the documentation
a priority to them. Generally, people avoid things they don't think is
valuable. 

> The idea of the form is to use
> it as a kick-off -- based on the form, in an ideal world, I would sit
down
> with the manager, and we would draft a TOC together while singing songs
and
> holding hands, and combing each others' hair (we're big on multi-tasking
> here). The form is meant as an starting poing, a preliminary
> information-gathering tool.

Good luck. THe person developing the TOC should be you and you alone.
Management should merely nod in approval. 

> I have a good relationship with the developers, but I don't have the
time to
> sit with them through the reviews.  If I've got 3 documents (different
> products) 200 pages each, being reviewed by 6 developers, and I'm
working on
> 3 new documents, where do I find the time? 

Make time. Sorry, but that is not a particularly heavy load. I've handled
19 docs of 1500 pages or more with 20+ developers. It was hard, but you
have to organize your time effectively. Moreover, if you know the
technology really well, most tech reviews will be a breeze. I rarely have
engineers changing my content. 

> So please, enlighten me, how do
> YOU develop special relationships with the developers?  When do YOU
schedule
> reviews?  How are they done?  Are you present?  Do you give them donuts?

Know the answers to questions before you ask them.

In other words, you learn the technologies so you can communicate with the
engineers at a highly technical level. You add value to their designs and
contribute content to their work. 
> Please, enlighten me.  Give me something I can work with.

You're asking for a panacea, Susie and there isn't one. In my decades of
working with technology and tech writing I have never once seen the
"Perfect Process".  It simply does not exist. 

What works is a combination of things. For one, you need to be more
proactive and assault the issues before somebody else complains. You need
to be working "ahead of the curve" not behind it. You're trying to
document things that already exist. That's easy and doesn't add value. You
need to work ahead of the engineers and be a proactive and involved part
of the development process. If people perceive you as an annoying
"administrative overhead" they won't spend time with you. 

Process works only when it develops "naturally." Forced process just to
fulfill the needs of some consultant's theories won't make you get your
work done faster. 

> Well written, but not very helpful.  I need something more concrete. 

YOu could always quit your job and open a flower stand. 

You're asking us to just hand you a perfect process that will soothe all
your ills. I suspect your corporate ills are deeper than just engineers
not reviewing your docs. Nobody here on TECHWR_L can just hand you the
answer. We can give you ideas and thoughts. I gave you one: work on your
relationship with your engineers. How:

1. Ask thoughtful questions that you have already formulated an answer
for. 
2. Engage them on a technical level - not merely on a functional level.
3. Ask them to explain why things are done a certain way.
4. Demonstrate your expertise with the product.
5. Research the issue, offer insights.
6. Test the product, use it, ask them to explain their reasoning behind
certain decisions.

You want to know what the closest thing to a perfect process: The
Scientific Method. Its simple, its easy, and you learned it when you were
10.

1. Observe
2. Hypothesize
3. Research
4. Test.
5. Document your findings

Practice this simple method in everything you do and I guarantee you will
start to improve your relationship with your engineers. 

>  I've
> been lurking in this group forever, and I've always been scared to post
any
> questions for fear of getting a response from you.  I know you don't
like
> process, and if that's the case, you should refrain from answering
> process-related questions.  Because you don't believe in it doesn't make
it
> any less valid to the peopl who do.

You should not fear me, although many writers do. And I know why - I say
what they don't want to hear. A lot of tech comm institutions have a lot
of writers believing that all they need are some templates, a process, and
good grammar to document mind-bendingly complex technologies. 

The reality is - you need a lot more. And it sounds like you're
confronting that.

Honestly - I envy you. You have a challenge in front of you that is
daunting and complex. That is the best position in the world to be in
because it truly shows what a person is made of. Maybe its a Koybashi Maru
(a no-win scenario). But as Kirk would say - how we deal with death is as
least as important as how we deal with life.

Andrew Plato 



__________________________________________________
Do You Yahoo!?
Great stuff seeking new owners in Yahoo! Auctions! 
http://auctions.yahoo.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for only $299, through January 31st. RoboHelp can import your
existing Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

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