Document Process Description Online?

Subject: Document Process Description Online?
From: David Neeley <dbneeley -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com, Nancy Allison <maker -at- verizon -dot- net>
Date: Wed, 7 Apr 2010 12:00:37 +0300


Please note that the "ideal" documentation process is not a single
process, but is related to the software architecture at the least. A
process that would work well with a traditional top-down or
"waterfall" methodology may be completely inappropriate for an agile
process, for instance.

In my experience, it is nearly impossible to become involved too early
in the product lifecycle. I have even volunteered in the past to take
notes at the preliminary product planning meetings in order to
contribute to the entire process. My goal was to have some input on
the user interface issues (to give one example). My reasoning was that
if the UI were properly done, customer satisfaction would be enhanced
and both tech support and documentation would be simpler.

I was happiest, in fact, when I wound up writing the requirements
documents based on the outcome of the various planning meetings.
Surprisigly often, I found issues that were easily disposed of but
which had not been obvious to various of the parties involved. Often,
this was a function of different understandings between management,
marketing, and engineering. Normally, these issues are things a good
product manager will ferret out, but as always they are best resolved
earlier in the process than later.

As far as I know, the original Software Development LIfecycle process
was first addressed by the Software Engineering Institute of Carnegie
Mellon University. They have gone well beyond that with their work
involving the Capability Maturity Models, which allow a formalized
assessment of your organization and its ability to effectively deal
with its product goals in a repeatable and effective manner. In 2006,
they released the latest downloadable document regarding the
integration of various of the CMMs designed for different processes
and goals--the CMMI, or Capability Maturity Model Integration document
is available from

If the objective of your assignment is part of an organizational
assessment of its own processes and an attempt to do some process
improvement efforts, it may be worth downloading and at least being
aware of the issues outlined in this document.

They have other resources, too, that may be worth exploring in your situation.

For example, from Rethinking the Software LIfecycle at

Life-Cycle Stage
Architecture-Based Activity

Business Needs and Constraints * Create a documented set of
business goals--issues/environment, opportunities, rationale, and
constraints--using a business presentation template

Requirements * Elicit and document
six-part quality attribute scenarios using general scenarios, utility
trees, and scenario brainstorming

Architecture Design * Design the architecture
using the ADD method steps
* Document the
architecture using multiple views
* Analyze the
architecture using some combination of the ATAM, ARID, and CBAM

Detailed Design * Validate the usability
of high-risk parts of the detailed design using an ARID review

Maintenance * Update documented set of
business goals using a business presentation templat
* Collect use case,
growth, and exploratory scenarios using general scenarios, utility
trees, and scenario brainstorming
* Design the new
architecture strategies using the ADD method steps
* Augment the
collected scenarios with a range of response and associated utility
values (creating a utility-response curve); determine the costs,
expected benefits, and return on investment (ROI) of all architectural
strategies using the CBAM steps
* Make decisions among
architecture strategies based on ROI, using the CBAM results

Notice how many references to "Document" in that listing? Ideally, you
and your colleagues should be involved pretty much at every step of
the process.


From: Nancy Allison <maker -at- verizon -dot- net>

> I've been asked for a soup-to-nuts description of the ideal documentation process.
> You know:
> Product (software or hardware) is proposed
> Product is OK'd by powers that be
> Marketing specifications developed
> Technical specs developed
> Development begins
> Alpha
> Beta
> Release
> Life of product
> Retirement of product
> and where documentation begins its participation, and how.
> Before I write a process tailored to this client's needs, I thought I'd take a look at any sample doc process writeups that are available online.
> Do you know of any that are squirreled away on STC web sites, or other professional sites?
> Thanks!
> --Nancy

Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial:

Explore CAREER options and paths related to Technical Writing,
learn to create SOFTWARE REQUIREMENTS documents, and
get tips on FUNCTIONAL SPECIFICATION best practices. Free at:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

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

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Previous by Author: RE: How do I recover my old stuff?
Next by Author: Re:Indexes for online use
Previous by Thread: Re: Document Process Description Online?
Next by Thread: Billable hours and building a sustainable consultancy

What this post helpful? Share it with friends and colleagues:

Sponsored Ads