Looks like we'll have to agree...

[Susie Pearson <spearson -at- espial -dot- com>]

to disagree.

Sorry, I'm not asking for anyone to hand me a process, I'm asking my peers
how documentation projects are kicked off at their company. I would like to
compare how things are done (or not done) at my company to how things are
done elsewhere.  I could use this feedback to try and institute some sort of
process here that would make things a little smoother on our docs department
(both of us!)  Part of the problem stems from the fact that I was gone for 9
months, and upon my return, when reading the docs to get back up to speed, I
saw that my replacement had made some grievous errors and ommissions in the
documentation that went completely unnoticed, although a whole bunch of ppl
signed off on the docs (the managers signed off saying "Yes, this is what I
asked for", and the developers signed off saying "Yes, this is technically
accurate").  

Anyhow, now, as the products keep evolving, I am left to pick up the pieces
and document all that was not documented for the past 9 months, in addition
to what is new.  I feel like I'm playing a constant game of 'catch up'.  The
problem is that there are no delta docs or an equivalent to tell me what was
changed while I was away, and when a product is re-released, there is no
consideration given to the documentation department. Documentation generally
isn't even in the project plan.  Don't think that I haven't talked to
management about it, because I have.  I think the value of the docs is
evidenced by the fact that customer service regularly consults them to solve
customer issues.  I am constantly pointing this out, and I meet with
customer service to get their feedback on the docs (they have been quite
helpful).  I am only asking for other people's input so that I can go to my
manger with a concrete plan, and when he asks "Why should we do it this
way?", I can say, "Well, I have been communicating with tech. writers from
other companies, and they have given me these suggestions."  That might have
a bit more clout than "Because I said so." 

And for the record, I am very close to the product, close enough that I do
internal and external training.  I am close enough that I can look at the
source code for the SDK and point out missing and redundant methods, and you
know what?  Developers don't like it when a lowly technical writer does
that.  It makes them look bad, and they've told me that.  So maybe if I dumb
it down a little, they might learn to like me more.  

The problem with having the docs done for RC (which means Beta where I am),
is that the first RC could always be the last -- there is no fixed number of
RCs that must be met.  How do I know that the first RC won't be the last?  I
can't have my docs done for RC.  It's just not possible. I can give them a
draft, but then what if the product is ready to go straight to Golden
Release?  

Thanks for your input, 

regards,
Susie Pearson

PS -- thanks for the flower stand idea. If all else fails, I might give it
serious consideration.

-----Original Message-----
From: Andrew Plato [mailto:intrepid_es -at- yahoo -dot- com]
Sent: Monday, January 28, 2002 12:38 PM
To: Susie Pearson; techwr-l -at- lists -dot- raycomm -dot- com
Subject: RE: where do docs fit in the development process?



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