Procedure How to Write a Manual!

[Bodvar Bjorgvinsson]

I agree that the writer must love the language, but he/she must
refrain from using "words such as 'transmogrify'" unless there is a
very good reason for it _and_ you have the word explained in the
"Terms and Definitions" section. ;-)
Have KISS in mind - as much as practicable, when writing technical manuals.

Regarding the "endianess", I had a problem some 13 years ago with some
UNIX software that was supposed to work on Linux. It did not. I sent a
query to an Icelandic guy on the "Basic Linux Training" list I
subscribed to and he came up with a solution. Then he expained to me
that there was a difference between Linux an UNIX that one used big
endian and the other little endian in the same code of software. The
first time I saw the term(s) I thought this must be a misspelling,
knowing that programmers often have weird kind of humor. What would it
be they referred to as Indians?

To this day I have not had any explanation understandable to me what
the real difference is. Neither have i had any problems with little or
big endians (or any sort of Indians) since. ;-)

Bodvar

2009/5/20 Reid Gray <rgray at interactivesupercomputing.com>:
> 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.
>
> _______________________________________________
>
>
> You are currently subscribed to Framers as bodvar at gmail.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/bodvar%40gmail.com
>
> Send administrative questions to listadmin at frameusers.com. Visit
> http://www.frameusers.com/ for more resources and info.
>



-- 
"Life is not only a game--it is also a dance on roses."
	--Fleksnes (Rolv Wesenlund)