Re: where do docs fit in the development process?

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

"Susie Pearson" wrote...

> Where I work, they want the
> final docs at the same time the release candidate is 
> given (with the final
> docs) to the test group.  This makes no sense -- we never have any time 
> with a solid product to check our documentation against it, and I do a 
> lot of QC when writing the documentation, so there are lots of changes 
> while I'm working on the 'final' copy.  

Sounds normal to me. Makes perfect sense to have docs done at RC1.

> Some backgound on the company -- small-ish company (approx. 75 ppl) with
a
> very immature process model for everything, but docs process is the
worst.

Normal again. Small companies rarely have highly developed processes. If
you want process and procedure, go work for a large firm. Small firms are
just not fertile ground for rigid process. 

>  We don't
> have the time for Hackos-type project planning / processes, but we need
> something more formal. 

Few places in the known universe have time, energy, or the cosmic matter
to use Hacko's methods to their fullest extent. 

> This form required information about the intended
> audience, resources, dependencies, draft dates, etc.  Unfortunately, the
> development managers had a hard time filling it out (really, it wasn't
that
> difficult, no math questions or anything).  

Never use a process to replace human contact. You can't expect people to
fill out forms. You should set up a meeting and talk to them about the
expectations for the docs. 

> I'm at the point now where my
> attitude is 'to hell with it', and I couldn't care less if the
documentation
> is crappy and late, because at least that will get somebody's attention,
and
> maybe things will change (I've been trying to change things myself for
over
> a year, but to no avail).  

How would you like it if the payroll department said - "Awww, hell with
it. We couldn't care less if Susie gets paid." 

> Oh yeah, and how do you get developers to review your docs?  I mean
actually
> read them?  

Develop a relationship with them. Earn their respect. 

> It's painfully obvious that these ppl aren't reviewing stuff,
> but no one seems to care.  
 
That is usually because they don't see any value. Your "hell with it"
attitude and demand for process probably isn't really getting them
interested in the work. 

You need to develop a working relationship with these people. Learn the
products, talk to them, get to know what they're doing. Get involved.
Process cannot replace involvement. 

> When I got back from maternity leave and found
> some *big* mistakes that should have been caught, ppl were very
nonchalant
> about it. 

Again, most people simply do not care about the things most writers care
about. You have to show that the documents have value. And when people are
nonchalant about the docs, its probably because nobody (namely you) has
shown them that they have any value. 

> I've implemented a sign-off, so that there's some accountability,
> but I don't want to pass the buck, I'd prefer our docs are reliable. 
I'm
> seriously considering flinging myself down on the floor in front of my
boss'
> office, and throwing a temper tantrum that would rival any two year
old's!

Again, you're trying to make process when a working relationship will
accomplish far more. Just because you have a sign-off form doesn't mean
you have actually established accountability. Just because people follow a
procedure doesn't mean the end result is positive. 

My suggestion is to stop worrying about the procedure and focus on
developing your relationships with your co-workers, namely the engineers.
In my experience, engineers will only read material if they believe the
documentation is adding value to the product(s). You need to demonstrate
to them that the docs add value. And from the sound of it, you haven't
done that. To do that, the documents must show the value of the
technology. Why it is useful and how it is effectively used. Merely
documenting each item and where to point and click won't do it.

You're not going to impress them with process. You have to impress them
with your knowledge and command of the technology and product. 

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.