How it works at my house (was: Engineering specs: The way it spo zed to be?

[mlist -at- safenet-inc -dot- com]

Steven Jong [mailto:stevefjong -at- comcast -dot- net] noted:

> Joe, you suggestions are fully in line with my experience. I'm  
> interested in why the VP of engineering says he doesn't expect--or  
> want--his engineers updating documents "every time they make a  
> change;" 

Funny you should mention that...
At our place, practice was to create a PRD (product requirements 
document) that included sections for each feature (including 
an omnibus section that would say something like "all 
functionality of previous product XYZ"). 

Each such section would describe the feature in general 
terms, then break it out into "requirements" that were 
needed in the hardware and software to make the feature 
happen.

That was called the "Engineering Response", along with 
any concerns about staff, tool, and material resources.

The whole entire document might have a handful of 
mandated "feature" sections, comprising hundreds of 
"requirements". That's what got signed off, and maybe 
updated once or twice before product release... or 
more likely some time after product release, but 
we won't go there. 

Anyway, a new development group manager added a 
section of "Issues" (since we currently use 
Rational's Clear Quest problem tracker, and it 
refers to problems as Issues). He then attempted 
to keep the list of issues-related-to-this-project 
up-to-date. That wasn't too bad, when each Requirement 
was an issue, and they mapped nicely.

But soon, it became apparent that:

a) engineers discover all sorts of interactions 
and problems as they go along just trying to 
make the requirements i)happen and ii) co-exist

b) engineering testers find all sorts of their 
own problems, some to do with the current attempt 
at implementation (of all those features and 
requirements), and some the result of the old 
and new versions of the product being integrated 
with third-party apps we never encountered before, 
or used in frightening new ways by customers we 
never had before...

We do have a rule that developers and coders 
do not work on anything unless that thing is 
an Issue in ClearQuest. In practice, an Issue 
can come from a customer requirement, a 
Marketing/Project requirement, a Customer 
Support trouble ticket, a QA or Engineering 
Test discovered problem, or a problem or 
bright idea of the developers themselves.
Any number of people can enter/create those 
things, but only the developer manager can 
assign them - which is how we gate the Issues 
and 

a) keep busybodies from piling work onto developers 
b) keep developers from going off into dreamland 
tangents and orgies of "wouldn't that be neat!"

So, either they work on stuff that others 
have raised, or they work on stuff that they 
have raised themselves, but only after it has 
been gated and approved. 

Still, this meant that all _kinds_ of new Issues 
would be generated, opened, closed, deferred, etc., 
that didn't map directly to formal features and 
requirements. 

Now, that isn't, in itself a problem - that's what 
an Issue-tracking system is for, after all - but 
the fact that the new manager was trying to 
keep that ever-expanding and convoluting list 
(which keeps expanding and convoluting even after 
so-called code-freeze) as part of the Product 
Requirements Document... _that_ was driving him nuts.
And the rest of us, too, as we'd repeatedly get 
asked to review-and-approve the next version of 
the PRD.

So, the long and the short of it is:

- you track your wishes and intentions in a 
requirements or design doc

- you track what you actually discover, and 
actually do, in the Issue tracking system

- don't try to combine those two functions 
unless you are made of time and patience.

When the dust begins to settle, QA must use 
the requirements doc and the list of closed 
and deferred Issues to determine what-and-how 
they are going to test.

So, all that to say that your developers and 
engineers should be recording what they do 
in some kind of problem/Issue/trouble-ticket 
tracking system, because they really shouldn't 
be making any changes that they don't document 
somewhere. And the trouble-ticket/Issue system 
has the big advantage of being public and 
standardized - developers that like to "document 
3000 lines of code with a 3-word comment are 
forced to put something sensible in the Issue 
tracking system. 
Needless to say, you-the-writer should have 
access to that system. In fact, you should 
have your own section of it for:

a) issues with the Customer documentation itself, 
which you would fix, then record where/how you 
fixed

b) issues that can't be fixed (or won't be) and 
therefore must have explanations/alerts/workarounds 
documented in the Customer docs

c) issues that are fixed by developers, resulting 
in changes to the way the product works, that 
should be mentioned in the docs.

In my case, I follow that scheme, but I avoid some of 
the constraints on developers in that I can make 
my own self-generated changes to my docs (little 
improvements and niceties) that I don't record 
as Issues in the tracking system.  After all, 
my documents kinda document themselves.

Others' situations probably differ.

So, it's sneaking up on the end of Friday afternoon, 
and I have a nice, leisurely nine-mile walk home, 
mostly along bike trails and alongside the Experimental 
Farm.
Maybe something interesting or lovely will unfold 
along the way, slowly enough that I can get my 
camera out of the backpack before it's all over. 
Maybe Bambi and his Mom will meet me at the fence 
again, and not bound away while I'm fishing for 
the camera.   :-)

I could whip out the camera-phone much faster 
than the "real" camera, but fixed-focus 2 Megapixel 
just doesn't cut it, most of the time, does it.

Kevin

The information contained in this electronic mail transmission may be privileged and confidential, and therefore, protected from disclosure. If you have received this communication in error, please notify us immediately by replying to this message and deleting it from your computer without copying or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help 
format plus PDF, HTML and more. Flexible, precise, and efficient content 
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.