RE: Procedure How to Write a Manual!
I also have enjoyed reading the thread I started and appreciate everyone's input, it has helped me to keep a clear head regarding this issue. Rick PS: I am an Electrical Engineer who worked in Engineering, then in a Product Support and Field Service position before becoming a Technical Writer, so I guess I have been on both sides of this fence. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Andy Kass Sent: Friday, May 22, 2009 4:25 PM To: framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! I've enjoyed reading all the input on this thread, and I had a few more thoughts. Unfortunately, the way Reid writes it below, it looks like anyone can have the writer role. I would've written: 4. Technical Writer who knows enough to understand the SME, learns about the audience and its lingo, distills all the essentials out of these to make an easy to absorb document, and knows the tools and formats well enough to do it all quickly. In any job, I think people need their core skills but also an understanding and certain competency in the skills of those around them. To that extent, I'm sure engineers can and do write decent docs sometimes, but they're probably more efficient at their engineering tasks. I'm pretty sure we all know this, but it is exactly this that is important to communicate in the case of this pointy-haired boss. Nor does the boss seem to understand how a good writer can save money and improve customer satisfaction. To be a good writer, you also have to understand where management is coming from... BTW, I actually don't think it's productive for writers to use big words for the sake of using big words. Writers must use whatever words speak to their audience. Andy ak...@jaspersoft.com Date: Wed, 20 May 2009 14:51:39 -0400 From: Reid Gray rg...@interactivesupercomputing.com Subject: RE: Procedure How to Write a Manual! 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. ___ You are currently subscribed to Framers as rmelan...@spirecorp.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor p.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
Thanks Andy, I agree. If words stick to your gray matter, echo in your head like music, and if you can't help yourself from teasing them apart at their roots and stems you are probably in the right profession. To be a writer you need to love words. Also note endianness came originally from literature (Gulliver's Travels). Agreed. Writers use words to suit the lexicon of their audience. If you are writing for USA Today, it's best not to use the vocabulary of the Harvard Business Review. If you are writing a release note or a README, you wouldn't want the tone and vocabulary to be more in line with a low-level language programmer's guide. BTW: Great thread. Reid From: framers-boun...@lists.frameusers.com on behalf of Andy Kass Sent: Fri 5/22/2009 4:25 PM To: framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! I've enjoyed reading all the input on this thread, and I had a few more thoughts. Unfortunately, the way Reid writes it below, it looks like anyone can have the writer role. I would've written: 4. Technical Writer who knows enough to understand the SME, learns about the audience and its lingo, distills all the essentials out of these to make an easy to absorb document, and knows the tools and formats well enough to do it all quickly. In any job, I think people need their core skills but also an understanding and certain competency in the skills of those around them. To that extent, I'm sure engineers can and do write decent docs sometimes, but they're probably more efficient at their engineering tasks. I'm pretty sure we all know this, but it is exactly this that is important to communicate in the case of this pointy-haired boss. Nor does the boss seem to understand how a good writer can save money and improve customer satisfaction. To be a good writer, you also have to understand where management is coming from... BTW, I actually don't think it's productive for writers to use big words for the sake of using big words. Writers must use whatever words speak to their audience. Andy ak...@jaspersoft.com Date: Wed, 20 May 2009 14:51:39 -0400 From: Reid Gray rg...@interactivesupercomputing.com Subject: RE: Procedure How to Write a Manual! 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. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
I've enjoyed reading all the input on this thread, and I had a few more thoughts. Unfortunately, the way Reid writes it below, it looks like anyone can have the writer role. I would've written: 4. Technical Writer who knows enough to understand the SME, learns about the audience and its lingo, distills all the essentials out of these to make an easy to absorb document, and knows the tools and formats well enough to do it all quickly. In any job, I think people need their core skills but also an understanding and certain competency in the skills of those around them. To that extent, I'm sure engineers can and do write decent docs sometimes, but they're probably more efficient at their engineering tasks. I'm pretty sure we all know this, but it is exactly this that is important to communicate in the case of this pointy-haired boss. Nor does the boss seem to understand how a good writer can save money and improve customer satisfaction. To be a good writer, you also have to understand where management is coming from... BTW, I actually don't think it's productive for writers to use big words for the sake of using big words. Writers must use whatever words speak to their audience. Andy ak...@jaspersoft.com Date: Wed, 20 May 2009 14:51:39 -0400 From: Reid Gray rg...@interactivesupercomputing.com Subject: RE: Procedure How to Write a Manual! 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. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Procedure How to Write a Manual!
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 rg...@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-boun...@lists.frameusers.com on behalf of Richard Melanson Sent: Tue 5/19/2009 9:21 AM To: Robert Shelton; Avraham Makeler; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Robert Shelton Sent: Monday, May 18, 2009 2:32 PM To: Avraham Makeler; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@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 rmelan...@spirecorp.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor p.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info
Re: Procedure How to Write a Manual!
On Fri, May 22, 2009 at 8:36 AM, Bodvar Bjorgvinsson bod...@gmail.com wrote: 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 I also ran into endian while documenting a UNIX application. A subject-matter expert (SME) patiently explained it to me, though my impression at the time was that he was a little uncertain. Perhaps the uncertainty was about the explanation itself, not about his grasp of the concept. His explanation was simply that some processor chips interpret binary code (ones and zeroes) from the Big end and others Little end. So a binary number that appears like 1000 to one chip would appear as 0001 to the other. I forget whether the big end is on the left or the right. While it made enough sense to me to move on with my project, the whole endianness issue came up in the first place because he introduced it in explaining communication protocols. I was trying to understand why an illustration of two protocols communicating between computers didn't seem correct. It used two parallel lines; one for TCP/IP, and the other for another protocol. I was supposed to add a third protocol to the illustration, but a third parallel line didn't /quite seem proper. After a bunch of interviews with different SMEs, I was able to dig out the key: a particular protocol is indicated by code that precedes a packet of information, and usually also is appended to the packet. The codes identify the protocol, so the packet contents are processed correctly. All the packets move on the same network channel; each protocol is identified by different code around the packets. I corrected the illustration to indicate one communication line between the computers; sets of identifiers, like xpacketx ypackety zpacketz, indicated the x, y, and z protocols moving along the single line. In addition, if you haven't already, search Google for endian. Regards, Peter __ Peter Gold KnowHow ProServices ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
Ah ... the old NUXI problem. :) I also ran into endian while documenting a UNIX application. A subject-matter expert (SME) patiently explained it to me, though my impression at the time was that he was a little uncertain. Perhaps the uncertainty was about the explanation itself, not about his grasp of the concept. His explanation was simply that some processor chips interpret binary code (ones and zeroes) from the Big end and others Little end. So a binary number that appears like 1000 to one chip would appear as 0001 to the other. I forget whether the big end is on the left or the right. Uh ... if you are showing a binary number above, this is not quite right. The bits *within* the byte do not change their order in the two common ENDIAN types. It is the *order* of the bytes within memory that the processor accesses. And, depending on whether you are accessing the memory in 16 bit words or 32 bit words (and presumably nowadays, in 64 bit words) the outcome is different. Two final comments: 1. In my documents, I call it byte order rather than endianness. Much simpler and cleaner. KISS applies! 2. The term comes from Gulliver's Travels in Lilliput. The two countries could not agree on which end of the egg to crack first - the big or the little. Hence two camps ... same as in the computing world! :) Z ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Big and Little Endians [was: Re: Procedure How to Write a Manual!]
On Fri, 22 May 2009 13:36:11 +, Bodvar Bjorgvinsson bod...@gmail.com wrote: 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. In current computer systems, there are two kinds of endianess, called LSB (Least Significant Byte) first and MSB (Most Significant Byte) first. For any given system, what determines this is not the operating system (Linux, Windows, etc.), it's the processor (CPU). All Intel CPUs are LSB first; others, like Sun SPARC and Motorola 68K, are MSB first. So Linux on a Sun SPARC would be MSB first, but on an Intel box it would be LSB first. Technically, the difference is indeed *byte* order, not *bit* order (which is constant). Suppose you have a hex number 0xABCD. The most significant byte is 0xAB; the least significant byte is 0xCD. Now imagine that you store this number in memory at address 0. ;-) You will get: Location SPARC Intel 0xAB 0xCD 0001 0xCD 0xAB Well-designed programs where portability matters will work with *either* CPU. They do this by not caring what the storage order in memory is, and always accessing multibyte numbers through a set of functions that work regardless of byte order. For example, Mif2Go was originally developed on a Sun SPARC system, then ported to Windows very easily because it followed those design rules. There's actually a third flavor, but it was used only on the DEC PDP-11. Since the last of those is probably in the Smithsonian, you won't see it in current software. It is the same as Intel for two-byte numbers (shorts) but switches the byte pairs for 4-byte numbers (longs). So the number 0x12345678 is 0x34, 0x12, 0x78, 0x56. Endianness also affects Unicode, in the UTF-16 and UTF-32 encodings of it, but *not* in UTF-8. It is the reason for the UTF-16 BOM (Byte Order Mark), U+FEFF, In UTF-16 Big-endian (MSB first), the bytes are 0xFE 0xFF. In UTF-16 Little-endian (LSB first), they are 0xFF 0xFE. UTF-32 adds two zero bytes, before it for Big and after for Little. The Unicode BOM may also be used as an encoding signature, but I digress... ;-) Good thing it's Friday, eh? HTH! -- Jeremy H. Griffith, at Omni Systems Inc. jer...@omsys.com http://www.omsys.com/ ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Big and Little Endians [was: Re: Procedure How to Write a Manual!]
Wow! What an education for a Friday ;) I remember playing with DEC PDP-11's when I was a kid visiting my father's office. I used to play some pseudo-DD command line game and fool around with some graphics software that would draw overlapping circles fill them with a limited palette of colours (sort of early Venn diagrams). Good times -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Jeremy H. Griffith Sent: Friday, May 22, 2009 3:14 PM To: framers@lists.frameusers.com Subject: Big and Little Endians [was: Re: Procedure How to Write a Manual!] On Fri, 22 May 2009 13:36:11 +, Bodvar Bjorgvinsson bod...@gmail.com wrote: 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. In current computer systems, there are two kinds of endianess, called LSB (Least Significant Byte) first and MSB (Most Significant Byte) first. For any given system, what determines this is not the operating system (Linux, Windows, etc.), it's the processor (CPU). All Intel CPUs are LSB first; others, like Sun SPARC and Motorola 68K, are MSB first. So Linux on a Sun SPARC would be MSB first, but on an Intel box it would be LSB first. Technically, the difference is indeed *byte* order, not *bit* order (which is constant). Suppose you have a hex number 0xABCD. The most significant byte is 0xAB; the least significant byte is 0xCD. Now imagine that you store this number in memory at address 0. ;-) You will get: Location SPARC Intel 0xAB 0xCD 0001 0xCD 0xAB Well-designed programs where portability matters will work with *either* CPU. They do this by not caring what the storage order in memory is, and always accessing multibyte numbers through a set of functions that work regardless of byte order. For example, Mif2Go was originally developed on a Sun SPARC system, then ported to Windows very easily because it followed those design rules. There's actually a third flavor, but it was used only on the DEC PDP-11. Since the last of those is probably in the Smithsonian, you won't see it in current software. It is the same as Intel for two-byte numbers (shorts) but switches the byte pairs for 4-byte numbers (longs). So the number 0x12345678 is 0x34, 0x12, 0x78, 0x56. Endianness also affects Unicode, in the UTF-16 and UTF-32 encodings of it, but *not* in UTF-8. It is the reason for the UTF-16 BOM (Byte Order Mark), U+FEFF, In UTF-16 Big-endian (MSB first), the bytes are 0xFE 0xFF. In UTF-16 Little-endian (LSB first), they are 0xFF 0xFE. UTF-32 adds two zero bytes, before it for Big and after for Little. The Unicode BOM may also be used as an encoding signature, but I digress... ;-) Good thing it's Friday, eh? HTH! -- Jeremy H. Griffith, at Omni Systems Inc. jer...@omsys.com http://www.omsys.com/ ___ You are currently subscribed to Framers as jeff.coatswo...@jonassoftware.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/jeff.coatsworth%40jo nassoftware.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Big and Little Endians [was: Re: Procedure How to Write a Manual!]
Now I finally understand and, consequently revoke my warning words against using 'endianess' in a manual. :D What? I understand it, why shouldn't everyone else? :-/ Böðvar -- Enlightened on a Friday 2009/5/22 Jeremy H. Griffith jer...@omsys.com: On Fri, 22 May 2009 13:36:11 +, Bodvar Bjorgvinsson bod...@gmail.com wrote: 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. In current computer systems, there are two kinds of endianess, called LSB (Least Significant Byte) first and MSB (Most Significant Byte) first. For any given system, what determines this is not the operating system (Linux, Windows, etc.), it's the processor (CPU). All Intel CPUs are LSB first; others, like Sun SPARC and Motorola 68K, are MSB first. So Linux on a Sun SPARC would be MSB first, but on an Intel box it would be LSB first. Technically, the difference is indeed *byte* order, not *bit* order (which is constant). Suppose you have a hex number 0xABCD. The most significant byte is 0xAB; the least significant byte is 0xCD. Now imagine that you store this number in memory at address 0. ;-) You will get: Location SPARC Intel 0xAB 0xCD 0001 0xCD 0xAB Well-designed programs where portability matters will work with *either* CPU. They do this by not caring what the storage order in memory is, and always accessing multibyte numbers through a set of functions that work regardless of byte order. For example, Mif2Go was originally developed on a Sun SPARC system, then ported to Windows very easily because it followed those design rules. There's actually a third flavor, but it was used only on the DEC PDP-11. Since the last of those is probably in the Smithsonian, you won't see it in current software. It is the same as Intel for two-byte numbers (shorts) but switches the byte pairs for 4-byte numbers (longs). So the number 0x12345678 is 0x34, 0x12, 0x78, 0x56. Endianness also affects Unicode, in the UTF-16 and UTF-32 encodings of it, but *not* in UTF-8. It is the reason for the UTF-16 BOM (Byte Order Mark), U+FEFF, In UTF-16 Big-endian (MSB first), the bytes are 0xFE 0xFF. In UTF-16 Little-endian (LSB first), they are 0xFF 0xFE. UTF-32 adds two zero bytes, before it for Big and after for Little. The Unicode BOM may also be used as an encoding signature, but I digress... ;-) Good thing it's Friday, eh? HTH! -- Jeremy H. Griffith, at Omni Systems Inc. jer...@omsys.com http://www.omsys.com/ ___ You are currently subscribed to Framers as bod...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/bodvar%40gmail.com Send administrative questions to listad...@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) ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Big and Little Endians [was: Re: Procedure How to Write a Manual!]
On Fri, 22 May 2009 13:36:11 +, Bodvar Bjorgvinsson wrote: >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. In current computer systems, there are two kinds of "endianess", called "LSB (Least Significant Byte) first" and "MSB (Most Significant Byte) first". For any given system, what determines this is not the operating system (Linux, Windows, etc.), it's the processor (CPU). All Intel CPUs are LSB first; others, like Sun SPARC and Motorola 68K, are MSB first. So Linux on a Sun SPARC would be MSB first, but on an Intel box it would be LSB first. Technically, the difference is indeed *byte* order, not *bit* order (which is constant). Suppose you have a hex number 0xABCD. The most significant byte is 0xAB; the least significant byte is 0xCD. Now imagine that you store this number in memory at address 0. ;-) You will get: Location SPARC Intel 0xAB 0xCD 0001 0xCD 0xAB Well-designed programs where portability matters will work with *either* CPU. They do this by not caring what the storage order in memory is, and always accessing multibyte numbers through a set of functions that work regardless of byte order. For example, Mif2Go was originally developed on a Sun SPARC system, then ported to Windows very easily because it followed those design rules. There's actually a third flavor, but it was used only on the DEC PDP-11. Since the last of those is probably in the Smithsonian, you won't see it in current software. It is the same as Intel for two-byte numbers (shorts) but switches the byte pairs for 4-byte numbers (longs). So the number 0x12345678 is 0x34, 0x12, 0x78, 0x56. Endianness also affects Unicode, in the UTF-16 and UTF-32 encodings of it, but *not* in UTF-8. It is the reason for the UTF-16 BOM (Byte Order Mark), U+FEFF, In UTF-16 Big-endian (MSB first), the bytes are 0xFE 0xFF. In UTF-16 Little-endian (LSB first), they are 0xFF 0xFE. UTF-32 adds two zero bytes, before it for Big and after for Little. The Unicode BOM may also be used as an encoding signature, but I digress... ;-) Good thing it's Friday, eh? HTH! -- Jeremy H. Griffith, at Omni Systems Inc. http://www.omsys.com/
Big and Little Endians [was: Re: Procedure How to Write a Manual!]
Wow! What an education for a Friday ;>) I remember playing with DEC PDP-11's when I was a kid visiting my father's office. I used to play some pseudo-D command line game and fool around with some graphics software that would draw overlapping circles & fill them with a limited palette of colours (sort of early Venn diagrams). Good times -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Jeremy H. Griffith Sent: Friday, May 22, 2009 3:14 PM To: framers at lists.frameusers.com Subject: Big and Little Endians [was: Re: Procedure How to Write a Manual!] On Fri, 22 May 2009 13:36:11 +, Bodvar Bjorgvinsson wrote: >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. In current computer systems, there are two kinds of "endianess", called "LSB (Least Significant Byte) first" and "MSB (Most Significant Byte) first". For any given system, what determines this is not the operating system (Linux, Windows, etc.), it's the processor (CPU). All Intel CPUs are LSB first; others, like Sun SPARC and Motorola 68K, are MSB first. So Linux on a Sun SPARC would be MSB first, but on an Intel box it would be LSB first. Technically, the difference is indeed *byte* order, not *bit* order (which is constant). Suppose you have a hex number 0xABCD. The most significant byte is 0xAB; the least significant byte is 0xCD. Now imagine that you store this number in memory at address 0. ;-) You will get: Location SPARC Intel 0xAB 0xCD 0001 0xCD 0xAB Well-designed programs where portability matters will work with *either* CPU. They do this by not caring what the storage order in memory is, and always accessing multibyte numbers through a set of functions that work regardless of byte order. For example, Mif2Go was originally developed on a Sun SPARC system, then ported to Windows very easily because it followed those design rules. There's actually a third flavor, but it was used only on the DEC PDP-11. Since the last of those is probably in the Smithsonian, you won't see it in current software. It is the same as Intel for two-byte numbers (shorts) but switches the byte pairs for 4-byte numbers (longs). So the number 0x12345678 is 0x34, 0x12, 0x78, 0x56. Endianness also affects Unicode, in the UTF-16 and UTF-32 encodings of it, but *not* in UTF-8. It is the reason for the UTF-16 BOM (Byte Order Mark), U+FEFF, In UTF-16 Big-endian (MSB first), the bytes are 0xFE 0xFF. In UTF-16 Little-endian (LSB first), they are 0xFF 0xFE. UTF-32 adds two zero bytes, before it for Big and after for Little. The Unicode BOM may also be used as an encoding signature, but I digress... ;-) Good thing it's Friday, eh? HTH! -- Jeremy H. Griffith, at Omni Systems Inc. http://www.omsys.com/ ___ You are currently subscribed to Framers as jeff.coatsworth at jonassoftware.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/jeff.coatsworth%40jo nassoftware.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Big and Little Endians [was: Re: Procedure How to Write a Manual!]
Now I finally understand and, consequently revoke my warning words against using 'endianess' in a manual. :D What? I understand it, why shouldn't everyone else? :-/ B??var -- Enlightened on a Friday 2009/5/22 Jeremy H. Griffith : > On Fri, 22 May 2009 13:36:11 +, Bodvar Bjorgvinsson > wrote: > >>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. > > In current computer systems, there are two kinds of > "endianess", called "LSB (Least Significant Byte) > first" and "MSB (Most Significant Byte) first". > For any given system, what determines this is not > the operating system (Linux, Windows, etc.), it's > the processor (CPU). ?All Intel CPUs are LSB first; > others, like Sun SPARC and Motorola 68K, are MSB > first. ?So Linux on a Sun SPARC would be MSB first, > but on an Intel box it would be LSB first. > > Technically, the difference is indeed *byte* order, > not *bit* order (which is constant). ?Suppose you > have a hex number 0xABCD. ?The most significant > byte is 0xAB; the least significant byte is 0xCD. > Now imagine that you store this number in memory > at address 0. ?;-) ?You will get: > > Location ?SPARC ?Intel > ?0xAB ? 0xCD > 0001 ?0xCD ? 0xAB > > Well-designed programs where portability matters > will work with *either* CPU. ?They do this by not > caring what the storage order in memory is, and > always accessing multibyte numbers through a set > of functions that work regardless of byte order. > For example, Mif2Go was originally developed on > a Sun SPARC system, then ported to Windows very > easily because it followed those design rules. > > There's actually a third flavor, but it was used > only on the DEC PDP-11. ?Since the last of those > is probably in the Smithsonian, you won't see it > in current software. ?It is the same as Intel > for two-byte numbers (shorts) but switches the > byte pairs for 4-byte numbers (longs). ?So the > number 0x12345678 is 0x34, 0x12, 0x78, 0x56. > > Endianness also affects Unicode, in the UTF-16 > and UTF-32 encodings of it, but *not* in UTF-8. > It is the reason for the UTF-16 BOM (Byte Order > Mark), U+FEFF, ?In UTF-16 Big-endian (MSB first), > the bytes are 0xFE 0xFF. ?In UTF-16 Little-endian > (LSB first), they are 0xFF 0xFE. ?UTF-32 adds two > zero bytes, before it for Big and after for Little. > > The Unicode BOM may also be used as an encoding > signature, but I digress... ? ;-) ?Good thing > it's Friday, eh? > > HTH! > > -- Jeremy H. Griffith, at Omni Systems Inc. > ? ?http://www.omsys.com/ > ___ > > > 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)
RE: Procedure How to Write a Manual!
How to Write a Manual: 1. Buy 100 computers. 2. Find 100 monkeys to sit at the computers. 3. Wait 100 years for synchronicity to kick in. Voila, you are done! Ben Hechter bhech...@objectives.ca www.semitake.com ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
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-boun...@lists.frameusers.com on behalf of Richard Melanson Sent: Tue 5/19/2009 9:21 AM To: Robert Shelton; Avraham Makeler; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Robert Shelton Sent: Monday, May 18, 2009 2:32 PM To: Avraham Makeler; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@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 rmelan...@spirecorp.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor p.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Procedure How to Write a Manual!
On Thu, May 14, 2009 at 1:58 PM, Richard Melanson rmelan...@spirecorp.com wrote: I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. The first part about a procedure is not so far-fetched in a regulation and standards-rich environment. The procedure won't be a literal step-by-microcosmic step description of what happens, but it will set out the requirements of the process and final product. Your circumstances, however, may not be so heavy on the regulations and standards. That second part about anyone can do it, though... that looks like the tip of some kind of iceberg. Is there someone else you can talk to in the organization who knows the context and players? Good luck. -- Milan Davidovic http://altmilan.blogspot.com ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
Sure do Rick. It's actually a slide presentation on good manual design and development, including how to estimate the time it takes to develop several types of docs. I'm writing you directly so that the attachment will go through. Diane Gaskill Hitachi Data Systems == -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com]on Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers@lists.frameusers.com Subject: Procedure How to Write a Manual! First, thank you Everyone, you guys always have the answers to questions, even when I don't post questions :-) I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. Needless to say, I am still sitting at my desk trying to sort through the myriad of reactions I am having! I cant wait to hear everyone's thoughts. Rick PS: Does anyone have a procedure how to write a manual ;-) ___ You are currently subscribed to Framers as dgcal...@earthlink.net. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/dgcaller%40earthlink.net Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
-Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@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 arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
-Original Message- From: Avraham Makeler; framers@lists.frameusers.com Subject: Procedure How to Write a Manual! I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. Needless to say, I am still sitting at my desk trying to sort through the myriad of reactions I am having! I cant wait to hear everyone's thoughts. PS: Does anyone have a procedure how to write a manual ;-) ___ Now, if you are primarily a tech writer by vocation, you really are joking, right? You do know the procedure for writing a manual. You also understand that to eat an elephant, you have to know how to make it into hamburgers. Someone (you? your boss? his boss?...n?) is authorised *and therefore obliged by job description* to enforce a company policy regarding creation and maintenance of written procedures at all levels. If it's your job in the department to ensure that procedures have proper and sufficient documentation then your How to Write Procedures procedure should be in circulation already. Is it? At 02:50 AM 19/05/2009, Flato, Gillian wrote: Your boss is a Jackass with poor people skills. If How to Write Procedures is already in circulation, why does the boss have to ask for it? Is it good enough? (Does it work?) Does he know it exists? Can he read? If not - isn't he just doing his Boss job? Shouldn't you be grateful that he's only insulting you, when he'd really like to have your guts for garters? Gillian wrote: He just told you that he doesn't appreciate or value you or your job. If layoff time comes, you're the first to go since anyone can be a writer and what's the fuss. It could have quite a different readingif he really believed that it were so easy, he would have written the How to Write a Manual procedure himself, handed it to you and told you to go get. Maybe he did...and you didn't. Your boss is not *totally* out of his tree if he means that anyone could be a provider of essential content for procedure documentation. To arrive at the state where there is a company manual encompassing every procedure in the organisation *requires* the responsible experts in each domain to abstract and articulate the right way to do every task. In this sense, even a dyslexic paint-blender must be able to perform as a content informant for the written paint-blending procedure -- even if you have to provide how-to videos of the questions each informant has to answer and voice recorders to capture the answers. It's time to transfer to another dept in your company or polish your resume and look for another job. On the other hand, if it's Avram's job to make the company manual happen, and it's not happening, then keeping the resume as-is could be safer... ;-) Helen ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Procedure How to Write a Manual
On Facebook this would be tagged Like! by many. :-) Bodvar Bjorgvinsson 2009/5/18 stre...@rcn.com: If anyone can write a manual, why do you need to write a procedure for doing it? Let your boss do it if he thinks it's so easy. ___ You are currently subscribed to Framers as bod...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/bodvar%40gmail.com Send administrative questions to listad...@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) ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Procedure How to Write a Manual!
No, this is obviously step #1. Art Campbell art.campb...@gmail.com ... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl. -- Richard Thompson No disclaimers apply. DoD 358 On Sun, May 17, 2009 at 10:43 PM, Martin Simon martin.si...@wetdesign.com wrote: 15. Update resume' . :) On May 17, 2009, at 5:42 PM, Sharon Burton sha...@anthrobytes.com wrote: 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. sharon Sharon Burton 951-369-8590 IM: sharonvbur...@yahoo.com Blog: madcapsoftware.wordpress.com -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers@lists.frameusers.com Subject: Procedure How to Write a Manual! First, thank you Everyone, you guys always have the answers to questions, even when I don't post questions :-) I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. Needless to say, I am still sitting at my desk trying to sort through the myriad of reactions I am having! I cant wait to hear everyone's thoughts. Rick PS: Does anyone have a procedure how to write a manual ;-) ___ ___ You are currently subscribed to Framers as martin.si...@wetdesign.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/martin.simon%40wetdesign.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as art.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
Sorry, guys. I don't know why the line breaks vanished! sharon Sharon Burton 951-369-8590 IM: sharonvbur...@yahoo.com Blog: madcapsoftware.wordpress.com -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Sharon Burton Sent: Sunday, May 17, 2009 5:43 PM To: 'Richard Melanson'; 'Avraham Makeler'; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! 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. sharon Sharon Burton 951-369-8590 IM: sharonvbur...@yahoo.com Blog: madcapsoftware.wordpress.com ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
Your boss is a Jackass with poor people skills. He just told you that he doesn't appreciate or value you or your job. If layoff time comes, you're the first to go since anyone can be a writer and what's the fuss. It's time to transfer to another dept in your company or polish your resume and look for another job. -Gillian -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers@lists.frameusers.com Subject: Procedure How to Write a Manual! First, thank you Everyone, you guys always have the answers to questions, even when I don't post questions :-) I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. Needless to say, I am still sitting at my desk trying to sort through the myriad of reactions I am having! I cant wait to hear everyone's thoughts. Rick PS: Does anyone have a procedure how to write a manual ;-) ___ You are currently subscribed to Framers as gfl...@nanometrics.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/gflato%40nanometrics .com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Procedure How to Write a Manual!
15. Update resume' .:) On May 17, 2009, at 5:42 PM, Sharon Burton sha...@anthrobytes.com wrote: 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. sharon Sharon Burton 951-369-8590 IM: sharonvbur...@yahoo.com Blog: madcapsoftware.wordpress.com -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers@lists.frameusers.com Subject: Procedure How to Write a Manual! First, thank you Everyone, you guys always have the answers to questions, even when I don't post questions :-) I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. Needless to say, I am still sitting at my desk trying to sort through the myriad of reactions I am having! I cant wait to hear everyone's thoughts. Rick PS: Does anyone have a procedure how to write a manual ;-) ___ ___ You are currently subscribed to Framers as martin.si...@wetdesign.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/martin.simon%40wetdesign.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Procedure How to Write a Manual!
I just want to share this with the list and absorb the response. My boss today told me to write a procedure on how to write a manual and he also stated to me that anyone could be a writer, he did not understand what all the fuss was about tech writing, anyone could do it. Needless to say, I am still sitting at my desk trying to sort through the myriad of reactions I am having! I cant wait to hear everyone's thoughts. Easy! It's a two- or three-step procedure that takes only five minutes: Step 1. Go to this link on Amazon: http://www.amazon.com/s/ref=nb_ss_b?url=search-alias%3Dstripbooksfield-keywords=How+to+write+a+manual and select one of the books about how to write a manual. Or go here: http://www.amazon.com/s/ref=nb_ss_b?url=search-alias%3Dstripbooksfield-keywords=technical+writing for tech writing books. Step 2. Send your selection to your boss. Step 3. (Optional, but recommended) Go here: http://www.amazon.com/When-Smart-People-Work-Bosses/dp/0070391475/ref=sr_1_6?ie=UTF8s=booksqid=1242618679sr=1-6 and buy _When Smart People Work for Dumb Bosses._ Send it to yourself. Warning! Do not mix up steps 2 and 3! : ) Mike Wickham P.S. You have my sympathy. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
