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 at 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
akass at jaspersoft.com
> Date: Wed, 20 May 2009 14:51:39 -0400
> From: "Reid Gray"
> 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 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.
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-bounces at lists.frameusers.com] On Behalf Of Andy Kass Sent: Friday, May 22, 2009 4:25 PM To: framers at 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 akass at jaspersoft.com > Date: Wed, 20 May 2009 14:51:39 -0400 > From: "Reid Gray" > 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 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.
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"
> 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 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" > 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!
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" > 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!
The wikipedia definition can be found at http://en.wikipedia.org/wiki/Endianness _ Hotmail® goes with you. http://windowslive.com/Tutorial/Hotmail/Mobile?ocid=TXT_TAGLM_WL_HM_Tutorial_Mobile1_052009 ___ 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!]
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)
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&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.
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 : > 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 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.
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 : > 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 > > Se
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 akass at jaspersoft.com > Date: Wed, 20 May 2009 14:51:39 -0400 > From: "Reid Gray" > 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.
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-D&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-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 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.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.
Procedure How to Write a Manual!
The wikipedia definition can be found at http://en.wikipedia.org/wiki/Endianness _ Hotmail? goes with you. http://windowslive.com/Tutorial/Hotmail/Mobile?ocid=TXT_TAGLM_WL_HM_Tutorial_Mobile1_052009
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 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/
Procedure How to Write a Manual!
On Fri, May 22, 2009 at 8:36 AM, Bodvar Bjorgvinsson 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
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
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.
Re: Procedure How to Write a Manual!
On Fri, May 22, 2009 at 8:36 AM, Bodvar Bjorgvinsson 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!
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 : > 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...@fra
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.
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 bhechter at objectives.ca www.semitake.com
Procedure How to Write a Manual!
How about Technical Writing: Process and Product, by Sharon Gerson? I picked that one because it's 700 pages and $95 in paperback. Tell the PHB that it would be cheaper than paying you to write it. Also faster. Good luck! Cheryl Bowsher Las Vegas ___ 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.
Procedure How to Write a Manual!
On Thu, May 14, 2009 at 1:58 PM, Richard Melanson 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
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 at lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@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.
Re: Procedure How to Write a Manual!
On Thu, May 14, 2009 at 1:58 PM, Richard Melanson 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!
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.
Procedure How to Write a Manual!
How about Technical Writing: Process and Product, by Sharon Gerson? I picked that one because it's 700 pages and $95 in paperback. Tell the PHB that it would be cheaper than paying you to write it. Also faster. Good luck! Cheryl Bowsher Las Vegas
RE: Procedure How to Write a Manual!
OUCH ! ;-) -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 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.
Procedure How to Write a Manual
On Facebook this would be tagged "Like!" by many. :-) Bodvar Bjorgvinsson 2009/5/18 : > 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 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)
Procedure How to Write a Manual!
>-Original Message- >From: Avraham Makeler; framers at 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
Procedure How to Write a Manual!
OUCH ! ;-) -Original Message- From: framers-boun...@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.
Re: Procedure How to Write a Manual
On Facebook this would be tagged "Like!" by many. :-) Bodvar Bjorgvinsson 2009/5/18 : > 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!
>-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!
> -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.
Procedure How to Write a Manual
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 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.
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
Procedure How to Write a Manual
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.
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-bounces at lists.frameusers.com] On Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers at 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 gflato at nanometrics.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/gflato%40nanometrics .com Send administrative questions to listadmin at 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.
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-bounces at lists.frameusers.com]On Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers at 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 dgcaller at earthlink.net. 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/dgcaller%40earthlink.net Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Procedure How to Write a Manual!
No, this is obviously step #1. Art Campbell art.campbell at 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 wrote: > 15. Update resume' . ? ?:) > > > > On May 17, 2009, at 5:42 PM, "Sharon Burton" > 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: sharonvburton at yahoo.com >> Blog: madcapsoftware.wordpress.com >> >> >> -Original Message----- >> From: framers-bounces at lists.frameusers.com >> [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Richard >> Melanson >> Sent: Thursday, May 14, 2009 10:58 AM >> To: Avraham Makeler; framers at 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.Simon at wetdesign.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/martin.simon%40wetdesign.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 art.campbell 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/art.campbell%40gmail.com > > Send administrative questions to listadmin at 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.
Procedure How to Write a Manual!
Sorry, guys. I don't know why the line breaks vanished! sharon Sharon Burton 951-369-8590 IM: sharonvburton at yahoo.com Blog: madcapsoftware.wordpress.com -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon Burton Sent: Sunday, May 17, 2009 5:43 PM To: 'Richard Melanson'; 'Avraham Makeler'; framers at 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: sharonvburton at yahoo.com Blog: madcapsoftware.wordpress.com
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 wrote: > 15. Update resume' . :) > > > > On May 17, 2009, at 5:42 PM, "Sharon Burton" > 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.
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%3Dstripbooks&field-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%3Dstripbooks&field-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=UTF8&s=books&qid=1242618679&sr=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.
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%3Dstripbooks&field-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%3Dstripbooks&field-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=UTF8&s=books&qid=1242618679&sr=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.
Re: Procedure How to Write a Manual!
15. Update resume' .:) On May 17, 2009, at 5:42 PM, "Sharon Burton" 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.
Procedure How to Write a Manual!
15. Update resume' .:) On May 17, 2009, at 5:42 PM, "Sharon Burton" 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: sharonvburton at yahoo.com > Blog: madcapsoftware.wordpress.com > > > -Original Message- > From: framers-bounces at lists.frameusers.com > [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Richard > Melanson > Sent: Thursday, May 14, 2009 10:58 AM > To: Avraham Makeler; framers at 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.Simon at wetdesign.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/martin.simon%40wetdesign.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info.
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 -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 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.
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: sharonvburton at yahoo.com Blog: madcapsoftware.wordpress.com -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Richard Melanson Sent: Thursday, May 14, 2009 10:58 AM To: Avraham Makeler; framers at 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 ;-) ___
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 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.
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 ;-)
