Re: Help - my consultants cannot write!

Subject: Re: Help - my consultants cannot write!
From: John Garison <john -at- garisons -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sat, 08 Oct 2011 23:17:18 -0400

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:

They are full-time, salaried employees. We don't have very many contractors.

Remember, our business is not writing, its security. We do pen-tests,
compliance auditing, forensics investigations, etc. We don't do tech
writing work.

And in many cases, good penetration testers or compliance experts are
not always good writers. Hence the request for some ideas on how to
educate these people on better writing techniques.

Andrew Plato

On Sat, Oct 8, 2011 at 1:25 PM, Gene Kim-Eng<techwr -at- genek -dot- com> wrote:
So are these consultants W2 employees of your firm, or are they 1099s
consulting to you?

If the latter, why not just lay out your requirements to them, tell them you
expect the work they submit to meet those requirements and let them figure
out how to get the writing done or sub the editing out to someone? Doesn't
trying to train your consultants to follow a specific process run counter to
the IRS's rules for defining independent contractors?

Gene Kim-Eng
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as andrew -dot- plato -at- gmail -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/andrew.plato%40gmail.com


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
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as john -at- garisons -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/john%40garisons.com


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
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


References:
Help - my consultants cannot write!: From: Andrew Plato
Re: Help - my consultants cannot write!: From: Edwin Skau
Re: Help - my consultants cannot write!: From: Gene Kim-Eng
Re: Help - my consultants cannot write!: From: Andrew Plato

Previous by Author: Re: The legalese pages
Next by Author: Re: Job searching in this time of attrition....
Previous by Thread: Re: Help - my consultants cannot write!
Next by Thread: Re: Help - my consultants cannot write!


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

Sponsored Ads


Sponsored Ads