Re: Help - my consultants cannot write!

[John Garison <john -at- garisons -dot- com>]

One thing I have had success with in the past is an annotated outline. 
It provides very detailed 'writers instructions' that serves a double 
purpose: First, it tells the boss/client what they can expect to get so 
that they can give you the go ahead with a very good idea of what they 
can expect at the end and 2) it tells the writer just what to write.

It's hard to explain, but here's an example:

3. XMPL System Inputs
This section briefly (1 paragraph) lists and describes the types of 
inputs XMPL handles, and introduces the contents of the remainder of the 
chapter.
3.1  Data Sources
This section (about 3 pages) lists all the possible data sources 
alphabetically.  For each data source, it describes where the data comes 
from, what form it is originally in, and what you have to do before you 
can load in into XMPL.
3.2 Data Receiver
This section (about 3 pages) describes:
What the receiver does, including searching for specified files, 
ensuring that files are complete, writing an output file, and deleting 
the input files once they are successfully processed.
How the receiver works including how it uses wildcards, performs 
specified volume/library, or total disk searches, how it uses 
transaction lookup file (TLF) functions, and explains session functions.
What the receiver requires, including the TLF and its  purpose and 
contents, the data input files and their requirements, and the control 
parameters.
How to tune the receiver to handle specific transaction types
How sessions are established and controlled, and how they are affected 
by the TLF and control parameters
Information about the session output file that is created
3.2  Data Sources
This section, about 2 pages explains the data checking that XMPL 
performs automatically, including listing error messages 
(alphabetically) and their meanings;  explains the auxiliary checks that 
you can perform to obtain more detailed information;  and explains the 
process you must follow with error-free data.  There will be frequent 
references to Section 5: XMPL Data Correction.


Once this level of detail has been developed, it's pretty easy to get 
someone to fill in the details. If they have basic grammar or other 
writing skill deficiencies, they can be addressed (make them re-write to 
learn how to correct errors). I have had success with this approach 
working with programmers, especially when I sit down with them to work 
together to produce the annotated outline. After a few iterations, they 
may even be able to pick it up themselves.

My 2¢,

JG

PS: the material in the example is Copyrighted by John Garison


Andrew Plato said the following on 10/8/2011 4:32 PM: