RE: where do docs fit in the development process?

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

-----Original Message-----
From: Andrew Plato [mailto:intrepid_es -at- yahoo -dot- com]
Sent: Monday, January 28, 2002 10:36 AM
To: techwr-l -at- lists -dot- raycomm -dot- com
Cc: Susie Pearson
Subject: Re: where do docs fit in the development process?


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

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

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

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

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

==========
Agreed.
==========

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

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

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

==========
Ummm, I'm not following.  My point is that maybe if a doc was late, or
missing (sometimes we're not even notified that a doc is required, then
after the release, the manager asks "Oh, where is this, did you put it in
the build?"), some attention would be drawn to the fact that our
documentation *IS* suffering as a result of the lack of process.
================ 

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

=============
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? 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?
What?  I write my own code examples, I comb through their source code, and
make suggestions that are implemented.  I'm not worried about earning their
respect.  I think a large part of the problem stems from the fact that docs
are expected to be delivered at the same time as the project.  As I said
earlier, they have their own deliverables to worry about.  
===================

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

=============
Please, enlighten me.  Give me something I can work with.
=============

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. 

==============
Well written, but not very helpful.  I need something more concrete.  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.
=================

Andrew Plato

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

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