TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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 http://www.sei.cmu.edu/cmmi/tools/dev/download.cfm
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.
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
Implementation
Testing
Deployment
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.
>
> 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: http://www.doctohelp.com
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: http://www.ModernAnalyst.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
