Re: Quality of source material from Development

["Neil, John" <NEILJ -at- Firstline -dot- com>]

	Salan Sinclair <salansinclair -at- shaw -dot- ca> wrote:
	How much written information should software development department
provide
	for a technical writing department?
	Option 1. Enough for tech writers to write the documentation, with
few
	questions.
	Option 2. Enough for tech writers to get a complete scope but not
the
	details.
	Option 3. Enough for tech writers to get started, or whatever
information
	developers can provide in the time allowed.

The answer is, actually, in the process. At my company, there is a whole lot
of documentation for me to use because the whole process is documented,
starting from the business request. Each document builds from the previous
step(s) in such a way that there is a lot of cut and paste used to populate
the subsequent documents. First, the business writes down their business
requirements. The tech writer is not involved in that except to maintain the
template that they use. Then the project manager generates the Requirements
Analysis document that simply takes each business requirement and addresses
it technically. 

>From this document, the external design document describes at a high level
what will be required to be done (including GUI prototypes, data flow
charts...). The technical writer is involved from this External Design
phase, although the effort is still mainly on the shoulders of the
Development Manager. The Internal Design takes this to a detailed level
(describing the functions and methods etc that will be required to satisfy
the requirements set out in the External Design (which are based on the
Requirements Analysis, which are based on....). Again, mostly the work of
the Dev. Mgr. The tech writer, at this stage, writes a runbook based on the
Requirements and External Design. The Developers do their coding and keep
what we call a Unit Development Folder (UDF - this was something that I
instituted) where they keep notes on their work, including their unit
testing. The SIT tests are written by the tech writer, based on the Internal
Design (cut-paste and add 'results' column - not usually that simple, but
that is the intention) and he/she also writes the UAT plan based on the
External Design document. While testing is in progress, the writer writes
the user guide. The writer also interviews the development team, reviews
their UDFs, and sends out surveys that are the basis for the
Post-Implementation Report which is a legacy document used for review in
order to improve future development projects. Finally, the writer creates a
technical manual that is used by the support staff once the 'warranty period
(when developers support the application) is over. This document is a
combination of External, Internal, Runbook, and User Guide (heavily focussed
on the Internal Design document).

This way, the writer is responsible for collecting the technical data (this
is 'technical' writing, after all) but can do so slowly over the course of
the development project. Being in attendance at all development meetings
also allows even a minimally-technically-adept person such as myself to know
enough to write comprehensive, and accurate, documentation. 

In short, if the process is there, the technical side of the technical
writer's job is not too hard.

To expect or request more than the minimal amount of time from developers in
the development of documentation rather minimizes the benefit of having us
at all. Before I came here, there was no technical writer. Now we have two
and they cannot function without us!

John Neil
Technical Writer - CMI IT
416-865-0411 x6944
neilj -at- firstline -dot- 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

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

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