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)
