Procedure How to Write a Manual!

[Reid Gray]

I think the list agrees that not just anybody can write a good manual.  And "No," writers cannot be just "anybody."  They must be committed, they need to love language, and as Annie Dillard says "...you really need to like words...words such as 'transmogrify'"  
 
Or, if you will extend the metaphor to IT, "endianess."
 
The best writing happens as a collective effort with the writer at the center. So, for example, take manuals. To write a good manual, one needs:
1. Subject matter experts for authoritative content
2. Enthusiastic reviewers who know the audience and have exposure to the subject matter
3. Editors who know the language
4. The technical writer
 
Trying as a single individual to serve in roles 1 through 4 is possible, but the more 'eyes' you have scanning the pages the better the expected outcome.  This is especially true if you are writing complete books, manuals, and periodicals, from scratch. 
 
There is also an equally beneficial flip side to this postulate. If you find either "transmogrify" or "endianess" to be ugly, and if you think anybody in particular can plant a garden, repair an automobile, or write a technical manual, you might be management material.

________________________________

From: framers-bounces at lists.frameusers.com on behalf of Richard Melanson
Sent: Tue 5/19/2009 9:21 AM
To: Robert Shelton; Avraham Makeler; framers at lists.frameusers.com
Subject: RE: Procedure How to Write a Manual!

-----Original Message-----
From: framers-bounces at lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of Robert
Shelton
Sent: Monday, May 18, 2009 2:32 PM
To: Avraham Makeler; framers at lists.frameusers.com
Subject: RE: Procedure How to Write a Manual!

> -----Original Message-----
> From: framers-bounces at lists.frameusers.com
> [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon
> Burton
>
> This is easy. 14 steps:
>
> 1. Identify the audience
> 2. Identify the information needs of that audience (job aids, user
> guides, and so on) 3. Identify the tasks the audience needs to do 4.
> Identify the supporting info the audience needs to do those tasks 5.
> Identify the best way to deliver the information (PDF, help, others)
> 6. Create a plan that layout all this information 7. Assign time
> estimates to the plan 8. Decide what can be cut due to time
> limitations 9.
> Start creating the information, adapting to the changing product 10.
> Review by others 11. Make the review changes 12.
> Build "gold" candidates 13. Deliver the finals 14. Archive the finals,

> including all planning information
>
> Of course, these steps include a lot of embedded steps and domain
> knowledge in our field. But these are the steps.

I think you skipped something important:

1. Hire a tech writer.

Bob
"Let what comes, come,
Let what goes, go,
Find out what remains."
Sri Ramana Maharshi


_______________________________________________


You are currently subscribed to Framers as rmelanson at spirecorp.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor
p.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
_______________________________________________


You are currently subscribed to Framers as rgray at interactivesupercomputing.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.