RE: where do docs fit in the development process?

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Susie,

Andrew has never said he doesn't believe in process, he has said on numerous
occasions that process is no substitute for knowledge or content.  You have
to develop a process that fits your resources, not try to make your
resources fit somebody else's process. (I know Andrew doesn't need me to
come to his defense, but since I wholehearted agree with the philosophy of
minimal process to get the job done, I find Plato-bashing on process silly)

With that being said, it's unlikely that you would have finished docs by
your release candidate stage if your developers are not using a build
schedule.  Find out when the stuff is being turned over to your QA folks for
initial testing, and get as much of the doc done during that time frame.
Then when QA goes to regression test your release candidate, your docs are
available for the same kind of testing.  If there is no schedule for turning
over functionality in stages, then you have a bigger problem than creating a
documentation process.  Suggest that a build schedule and your milestones
are incorporated in the project plan.  Again if there's not at least a basic
project schedule that you have access to, you have a much bigger problem
than whether you can get doc signoffs.

I juggle 8 products, so I sympathize with not having the time, but it's
really up to you to take the initiative to learn the product, what it's
supposed to do and how it's supposed to do it.  Developers don't hold my
hand, and I don't waste their time with stuff I can research on my own.
That way when it's a real stumper or show-stopper, they don't ignore me.

The day I have a stable product to check documentation against is the day I
go look for another job.  I may not have QA in my title or official job
responsibilities, but I'm well-suited to finding all the weird stuff that
"dumb users" might find. I think it's kind of fun to try to break it. As a
result I've saved more than a bit of time during major releases by finding
show stoppers that developers or QA wouldn't have found.  Stability is a
matter of perception :).

Instead of trying to organize meetings about docs, make sure you can attend
meetings about the product, and get doc issues on the agenda.  Helps to
reinforce the idea that docs should have consideration prior to release.
Some of our products have weekly status meetings, some don't.  I had to get
myself invited to those, and tried to listen, learn and makes some useful
contributions.  Now I'm on the distribution lists for all the products I'm
responsible for.  Takes time, but it can be done.

When all else fails, consider offering to help write specs and design the
interface.  Many development teams love to have somebody take that off their
plates, and you have the advantage of being there, and getting the
information from the beginning.  Won't help much for the current release
candidates, but can put a little sanity in the process for the future.

I hope I've been able to give you a bit of concrete help.

Connie P. Giordano
Senior Technical Writer
Advisor Technology Services
A Fidelity Investments Company
704-330-2069 (w)
704-330-2350 (f)
704-957-8450 (c)
 
"I am always doing that which I can not do, in order that I may learn how to
do it." - Pablo Picasso 


-----Original Message-----
From: Susie Pearson [mailto:spearson -at- espial -dot- com]
Sent: Monday, January 28, 2002 11:06 AM
To: TECHWR-L
Subject: RE: where do docs fit in the development process?




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




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