RE: Confirmation: : Numbering Systems for Technical Service Manuals
Right you are, Peter. That's why the data storage and backup industries are thriving right now. The amount of data stored by businesses today is growing exponentially. Diane -Original Message- From: Peter Gold [mailto:[EMAIL PROTECTED] Sent: Friday, May 19, 2006 4:34 AM To: Diane Gaskill; Framers List Subject: Re: Confirmation: : Numbering Systems for Technical Service Manuals At 3:10 AM -0700 5/19/06, Diane Gaskill wrote: ALL of the documentation within the company - literally a billion pages or more - uses numbered headings. Yes, some of the docs are written by engineers to other engineers, but much of the product documentation goes to the customers, most of whom are not engineers. The same numbering scheme is used in Accounting, HR, IT, and every department in the company. As the movement towards enterprise-wide content management and structured information technologies, such as XML, to support smoother exchange of information and greater varieties of distribution, this kind of uniform standard is necessary. Only a billion pages? HA! Soon it will be billions and billions... Remember when McDonald's signs bragged about millions served? Regards, Peter Gold KnowHow ProServices ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Confirmation: : Numbering Systems for Technical Service Manuals
Right you are, Peter. That's why the data storage and backup industries are thriving right now. The amount of data stored by businesses today is growing exponentially. Diane -Original Message- From: Peter Gold [mailto:pe...@knowhowpro.com] Sent: Friday, May 19, 2006 4:34 AM To: Diane Gaskill; Framers List Subject: Re: Confirmation: : Numbering Systems for Technical Service Manuals At 3:10 AM -0700 5/19/06, Diane Gaskill wrote: > ALL of the >documentation within the company - literally a billion pages or more - uses >numbered headings. Yes, some of the docs are written by engineers to other >engineers, but much of the product documentation goes to the customers, most >of whom are not engineers. The same numbering scheme is used in Accounting, >>HR, IT, and every department in the company. As the movement towards enterprise-wide content management and structured information technologies, such as XML, to support smoother exchange of information and greater varieties of distribution, this kind of uniform standard is necessary. Only "a billion pages?" HA! Soon it will be "billions and billions..." Remember when McDonald's signs bragged about millions served? Regards, Peter Gold KnowHow ProServices
RE: Numbering Systems for Technical Service Manuals
At 11:16 -0700 18/5/06, Daniel Emory wrote: Nevertheless, this issue about numbering of titled headings, tables and graphics seems to come up frequently. It's a valid issue, and it deserves more discussion on the list. Surely the answer here is 'horses for courses'? There are many areas where numbering is either appropriate or essential (engineering manuals,legal documents, political documents, medical documents, repair manuals, ya-de-yah), and others where it is not. Legal is one special case: due to its density, every *paragraph* is often numbered. The problem comes in the gray areas, such as software user guides, where there is the option to use numbering or not to use numbering. Fwiw, my default preference is to cross-reference by section/subsection title and page where required (because, imho, section headings look better without numbers and page cross-references are the most user-friendly), but to number tables and figures. This default is easily (and often) overridden by client preferences. And just a vaguely relevant note on the intuitive software thread: having taught myself FrameMaker in the early 1990s, I started a contract where a large writing team were required to use Interleaf, none of whom had ever seen it before. Two weeks had been set aside for training and familiarization, but I and others like me who had already worked with a powerful DTP tool such as FrameMaker picked up 90% of Interleaf from scratch in a day or so. And Interleaf is (or was) substantially more arcane than FrameMaker. -- Steve ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
FM help and more: WAS: Numbering Systems for Technical Service Manuals
Hi Laura, When you run into a problem or are trying to learn a new feature and things (e.g., the help) don't make sense, please send a message to this list. I can almost guarantee that you'll have several answers within a few hours, or at least within 24. I've been on the list for 14 years and I couldn't possibly count all the helpful answers I've seen from hundreds of Frameratti on this list(I even wrote a few of them myself). Yes, there is a bit of babble sometimes and once in a while a contentious thread or two :-), but for the most part the list is here to support Frame users. From what I've seen, it does a darn good job. In my experience the help you get here is more accurate than the help you get from Adobe, because the members actually use FM every day to do their jobs. Many members are lng time Frame users who have learned things the hard way and who have run into the pitfalls and discovered the shortcuts to get things done easily. They can tell you about the holes before you fall into them. BTW, the FM GUI isn't all that difficult to use once you understand how they set it up. But I've been using FM since it was a baby and had to learn only a little bit at a time, as the app grew. I'm sure it's a lot to digest all at once. A comment about the FM help. I have copies of the FM users guides starting with 3.2, and I can tell you all for sure that Dan Emory is right. The early help (written by Frame Technology, I believe) consisted of two thick manuals and covered everything. It was a heckuva lot better than what we get now, even if it wasn't all on line. Apparently Adobe thinks that newbies don't need all that information any more, but I disagree. I've helped several coworkers and my staff members learn FM and I can tell you from my own experience that some of the info I learned in the early manuals cam in very handy. dunno if the curent help is quite as bad as shovelware (I never heard the term before and I am falling off my chair laughing as I write this), but as Yoda would say, Good it is not. Diane -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] Behalf Of [EMAIL PROTECTED] Sent: Thursday, May 18, 2006 12:08 PM To: Framers@frameusers.com Subject: RE: Numbering Systems for Technical Service Manuals I'm not familiar with versions of FM help prior to vers. 7, which I am using. That, I can agree wholeheartedly, sucks. As a self-taught FM user, it takes hours, literally hours to figure out some new operation or feature in Framemaker. Operations/features, I might add, that were pretty much intuitive in Pagemaker or Quark. If you're going to have a user-hostile interface, at least have some decent documentation. Most of the hours I spend trying to figure things out are spent searching forums on the Web. However, doing decent documentation costs money. Adobe obviously has saved a lot of money here. I feel as if, if I'm ever going to reach any level of proficiency with this program, it's going to mean going to a training class. Now, that's great for independent trainers, not so great for me, since I'll have to pay for something that IMHO shouldn't be needed. You should perhaps need training to be a power user ... not to just figure out how to perform common operations. ljk ___ Deja Moo: The feeling that you've heard this bull before. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Confirmation: : Numbering Systems for Technical Service Manuals
I work for a VERY large, nationwide government contractor. ALL of the documentation within the company - literally a billion pages or more - uses numbered headings. Yes, some of the docs are written by engineers to other engineers, but much of the product documentation goes to the customers, most of whom are not engineers. The same numbering scheme is used in Accounting, HR, IT, and every department in the company. The numbered headings make it easy for the reader to associate paragraphs together and definitely makes anything in the doc faster to locate, whether the doc is printed or online. We use links in the online docs too, but they are xrefs and include the numbered headings they refer to. Diane === -Original Message- From: Daniel Emory Sent: Thursday, May 18, 2006 8:31 AM To: Framers List Subject: RE: Numbering Systems for Technical Service Manuals - snip Clearly, many types of technical documentation other than engineer-to-engineer documents are enhanced by using a rational numbering scheme, and I cited many examples in my initial reply. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Confirmation: : Numbering Systems for Technical Service Manuals
At 3:10 AM -0700 5/19/06, Diane Gaskill wrote: ALL of the documentation within the company - literally a billion pages or more - uses numbered headings. Yes, some of the docs are written by engineers to other engineers, but much of the product documentation goes to the customers, most of whom are not engineers. The same numbering scheme is used in Accounting, HR, IT, and every department in the company. As the movement towards enterprise-wide content management and structured information technologies, such as XML, to support smoother exchange of information and greater varieties of distribution, this kind of uniform standard is necessary. Only a billion pages? HA! Soon it will be billions and billions... Remember when McDonald's signs bragged about millions served? Regards, Peter Gold KnowHow ProServices ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Numbering Systems for Technical Service Manuals
I appreciate everyone's feedback on this issue. I have learned a lot. So here's the long and short of what I did. After taking the numbered heads out of a very technical manual, my engineers asked me to put them back in. I talked to the software manager and he said that for this manual, (which is essentially an API), they use the numbers all the time. Our Field Service Engineers in Asia constantly call in and refer to those numbers as they talk about specific streams and functions in the application and get support from our in-house engineers. The end-user software manual has never had numbered heads and will remain that way. The API manual is typically only used by our FSEs. I LOVE the expertise on this list. It's WAY better than Adobe support. I like this list so much, I got my husband to join. He's also a Tech Writer. So are we the only couple on this list? g Just curious. Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * [EMAIL PROTECTED] blocked::mailto:[EMAIL PROTECTED] This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Numbering Systems for Technical Service Manuals
--- Steve Rickaby [EMAIL PROTECTED] wrote: Surely the answer here is 'horses for courses'? There are many areas where numbering is either appropriate or essential (engineering manuals,legal documents, political documents, medical documents, repair manuals, ya-de-yah), and others where it is not. Legal is one special case: due to its density, every *paragraph* is often numbered. == The essence of the reason for numbering in the document types I (and you) cited is multi-fold: 1. It eliminates ambiguity 2. It facilitates rapid access 3. It minimizes mistakes, and speeds up access, particularly when you are working off-line with a paper copy, in which case hyperlinks are unavailable. When you reference something by its title instead of by an unique number, it creates two problems: (a) How do you find it in a large document, whereas referencing by a number tells you exactly where it's located, and (b) technical manualsoften have many instances of very similar titles, and users are more likely to go to the wrong one. For these reasons, I contend that that nearly all technical manuals fall into the same category as engineering documents, legal documents, medical documents, etc., because all of those types share the urgent necessity of avoiding mistakes caused by looking up the wrong reference. Dan Emory Associates FrameMaker/FrameMaker+SGML Document Design Database Publishing [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Numbering Systems for Technical Service Manuals
At 11:16 -0700 18/5/06, Daniel Emory wrote: >Nevertheless, this issue about numbering of titled headings, tables and >graphics seems to come up frequently. It's a valid issue, and it deserves more >discussion on the list. Surely the answer here is 'horses for courses'? There are many areas where numbering is either appropriate or essential (engineering manuals,legal documents, political documents, medical documents, repair manuals, ya-de-yah), and others where it is not. Legal is one special case: due to its density, every *paragraph* is often numbered. The problem comes in the gray areas, such as software user guides, where there is the option to use numbering or not to use numbering. Fwiw, my default preference is to cross-reference by section/subsection title and page where required (because, imho, section headings look better without numbers and page cross-references are the most user-friendly), but to number tables and figures. This default is easily (and often) overridden by client preferences. And just a vaguely relevant note on the intuitive software thread: having taught myself FrameMaker in the early 1990s, I started a contract where a large writing team were required to use Interleaf, none of whom had ever seen it before. Two weeks had been set aside for training and familiarization, but I and others like me who had already worked with a powerful DTP tool such as FrameMaker picked up 90% of Interleaf from scratch in a day or so. And Interleaf is (or was) substantially more arcane than FrameMaker. -- Steve
FM help and more: WAS: Numbering Systems for Technical Service Manuals
Hi Laura, When you run into a problem or are trying to learn a new feature and things (e.g., the help) don't make sense, please send a message to this list. I can almost guarantee that you'll have several answers within a few hours, or at least within 24. I've been on the list for 14 years and I couldn't possibly count all the helpful answers I've seen from hundreds of Frameratti on this list(I even wrote a few of them myself). Yes, there is a bit of babble sometimes and once in a while a contentious thread or two :-), but for the most part the list is here to support Frame users. From what I've seen, it does a darn good job. In my experience the help you get here is more accurate than the help you get from Adobe, because the members actually use FM every day to do their jobs. Many members are lng time Frame users who have learned things the hard way and who have run into the pitfalls and discovered the shortcuts to get things done easily. They can tell you about the holes before you fall into them. BTW, the FM GUI isn't all that difficult to use once you understand how they set it up. But I've been using FM since it was a baby and had to learn only a little bit at a time, as the app grew. I'm sure it's a lot to digest all at once. A comment about the FM help. I have copies of the FM users guides starting with 3.2, and I can tell you all for sure that Dan Emory is right. The early help (written by Frame Technology, I believe) consisted of two thick manuals and covered everything. It was a heckuva lot better than what we get now, even if it wasn't all on line. Apparently Adobe thinks that newbies don't need all that information any more, but I disagree. I've helped several coworkers and my staff members learn FM and I can tell you from my own experience that some of the info I learned in the early manuals cam in very handy. dunno if the curent help is quite as bad as "shovelware" (I never heard the term before and I am falling off my chair laughing as I write this), but as Yoda would say, "Good it is not." Diane -Original Message- From: framers-bounces+dgcaller=earthlink@lists.frameusers.com [mailto:framers-bounces+dgcaller=earthlink.net at lists.frameusers.com]On Behalf Of Laura_J_Kirk at bd.com Sent: Thursday, May 18, 2006 12:08 PM To: Framers at frameusers.com Subject: RE: Numbering Systems for Technical Service Manuals I'm not familiar with versions of FM help prior to vers. 7, which I am using. That, I can agree wholeheartedly, sucks. As a self-taught FM user, it takes hours, literally hours to figure out some new operation or feature in Framemaker. Operations/features, I might add, that were pretty much intuitive in Pagemaker or Quark. If you're going to have a user-hostile interface, at least have some decent documentation. Most of the hours I spend trying to figure things out are spent searching forums on the Web. However, doing decent documentation costs money. Adobe obviously has saved a lot of money here. I feel as if, if I'm ever going to reach any level of proficiency with this program, it's going to mean going to a training class. Now, that's great for independent trainers, not so great for me, since I'll have to pay for something that IMHO shouldn't be needed. You should perhaps need training to be a "power user" ... not to just figure out how to perform common operations. ljk ___ Deja Moo: The feeling that you've heard this bull before.
Confirmation: : Numbering Systems for Technical Service Manuals
I work for a VERY large, nationwide government contractor. ALL of the documentation within the company - literally a billion pages or more - uses numbered headings. Yes, some of the docs are written by engineers to other engineers, but much of the product documentation goes to the customers, most of whom are not engineers. The same numbering scheme is used in Accounting, HR, IT, and every department in the company. The numbered headings make it easy for the reader to associate paragraphs together and definitely makes anything in the doc faster to locate, whether the doc is printed or online. We use links in the online docs too, but they are xrefs and include the numbered headings they refer to. Diane === -Original Message- From: Daniel Emory Sent: Thursday, May 18, 2006 8:31 AM To: Framers List Subject: RE: Numbering Systems for Technical Service Manuals - Clearly, many types of technical documentation other than engineer-to-engineer documents are enhanced by using a rational numbering scheme, and I cited many examples in my initial reply.
Confirmation: : Numbering Systems for Technical Service Manuals
At 3:10 AM -0700 5/19/06, Diane Gaskill wrote: > ALL of the >documentation within the company - literally a billion pages or more - uses >numbered headings. Yes, some of the docs are written by engineers to other >engineers, but much of the product documentation goes to the customers, most >of whom are not engineers. The same numbering scheme is used in Accounting, >>HR, IT, and every department in the company. As the movement towards enterprise-wide content management and structured information technologies, such as XML, to support smoother exchange of information and greater varieties of distribution, this kind of uniform standard is necessary. Only "a billion pages?" HA! Soon it will be "billions and billions..." Remember when McDonald's signs bragged about millions served? Regards, Peter Gold KnowHow ProServices
Numbering Systems for Technical Service Manuals
I appreciate everyone's feedback on this issue. I have learned a lot. So here's the long and short of what I did. After taking the numbered heads out of a very technical manual, my engineers asked me to put them back in. I talked to the software manager and he said that for this manual, (which is essentially an API), they use the numbers all the time. Our Field Service Engineers in Asia constantly call in and refer to those numbers as they talk about specific streams and functions in the application and get support from our in-house engineers. The end-user software manual has never had numbered heads and will remain that way. The API manual is typically only used by our FSEs. I LOVE the expertise on this list. It's WAY better than Adobe support. I like this list so much, I got my husband to join. He's also a Tech Writer. So are we the only couple on this list? Just curious. Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * gflato at nanometrics.com This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited.
Numbering Systems for Technical Service Manuals
--- Steve Rickaby wrote: > Surely the answer here is 'horses for courses'? > There are many areas where numbering is either > appropriate or essential (engineering manuals,legal > documents, political documents, medical documents, > repair manuals, ya-de-yah), and others where it is > not. Legal is one special case: due to its density, > every *paragraph* is often numbered. == The essence of the reason for numbering in the document types I (and you) cited is multi-fold: 1. It eliminates ambiguity 2. It facilitates rapid access 3. It minimizes mistakes, and speeds up access, particularly when you are working off-line with a paper copy, in which case hyperlinks are unavailable. When you reference something by its title instead of by an unique number, it creates two problems: (a) How do you find it in a large document, whereas referencing by a number tells you exactly where it's located, and (b) technical manualsoften have many instances of very similar titles, and users are more likely to go to the wrong one. For these reasons, I contend that that nearly all technical manuals fall into the same category as engineering documents, legal documents, medical documents, etc., because all of those types share the urgent necessity of avoiding mistakes caused by looking up the wrong reference. Dan Emory & Associates FrameMaker/FrameMaker+SGML Document Design & Database Publishing
RE: Numbering Systems for Technical Service Manuals
--- Linda G. Gallagher [EMAIL PROTECTED] wrote: I don't think it was necessary to single out my response and call what I said laughable. Your unqualified statement that the only people left who use such numbering schemes are engineers communicating with other engineers is what made it laughable, because your statement itself was insulting to the many technical disciplines where such numbering schemes are considered essential. Clearly, many types of technical documentation other than engineer-to-engineer documents are enhanced by using a rational numbering scheme, and I cited many examples in my initial reply. One could infer that your conclusion derives from the fact that your millieu is restricted to on-line help--the realm where shovelware reigns supreme. In general, that regime only works when the product being supported is some relatively simple piece of software, and on-line help is only useful to beginners, who would probably be better off if they could print a complete manual that actually looks like a technical manual when it is printed. The general assumption of on-line help developers seems to be that links are a substitute for a rational numbering scheme. You may be surprised to learn that there are vast realms in which selected technical manual content must be printed out in order to successfully carry out tasks, and thus links no longer work. in those cases, a rational numbering scheme in the printed portion replaces links as the method for finding (and printing) referenced content. That's an unnecessary insult. == Your statement itself insulted those who produce technical content that is far superior to the typical on-line help shovelware. == As for this particular issue, I know of few writers and companies who advocate using numbered sections as you suggest. == How many companies or writers do you know who work outside the realm of on-line help shovelware? Dan Emory Associates FrameMaker/FrameMaker+SGML Document Design Database Publishing [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Numbering Systems for Technical Service Manuals
Is this a private email from Linda that you posted to the list? How completely rude. *That* is surely a netiquette violation, I've never been on an email list or newsgroup where it was tolerated. Anne -Original Message- From: [EMAIL PROTECTED] com [mailto:[EMAIL PROTECTED] meusers.com] On Behalf Of Daniel Emory Sent: Thursday, May 18, 2006 11:31 AM To: [EMAIL PROTECTED] Cc: Framers List Subject: RE: Numbering Systems for Technical Service Manuals --- Linda G. Gallagher [EMAIL PROTECTED] wrote: I don't think it was necessary to single out my response and call what I said laughable. The information contained in or attached to this e-mail contains confidential or privileged information. If you are not the intended recipient, be aware that any disclosure, copying, distribution or use of the contents of this e-mail is PROHIBITED. If you have received this e-mail in error, please notify the sender and delete the e-mail immediately. Thank you. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Numbering Systems for Technical Service Manuals
--- Anne Robotti [EMAIL PROTECTED] wrote: Is this a private email from Linda that you posted to the list? How completely rude. = My mistake, and I apologize to Linda. The Framer's list, unlike some others, identifies the sender's name, not the list's name as the sender. My default email setup only identifies the sender in the From line, thus, when I hit reply, only the sender's name appears in the To line. Since the thread originated on the Framers list, I presumptively added the list name on the cc line in my reply. I usually check first to see if that is proper, but this time I failed to do so. I'll be more careful in the future. My bad. Nevertheless, this issue about numbering of titled headings, tables and graphics seems to come up frequently. It's a valid issue, and it deserves more discussion on the list. And by the way, I do not apologize for describing most on-line help as shovelware. If that is offensive to some, so be it. The FrameMaker on-line help in versions 4 and earlier was far superior to the shovelware that replaced it in later versions. That, coupled with the much less complete printed manual, makes life more difficult for newbies. Many of the FrameMaker issues which come up over and over again on this list should be answered by declaring RTFM. Unfortuantely, that recommendation no longer applies in many cases. The same goes for the Acrobat manual. Dan Emory Associates FrameMaker/FrameMaker+SGML Document Design Database Publishing [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Numbering Systems for Technical Service Manuals
I'm not familiar with versions of FM help prior to vers. 7, which I am using. That, I can agree wholeheartedly, sucks. As a self-taught FM user, it takes hours, literally hours to figure out some new operation or feature in Framemaker. Operations/features, I might add, that were pretty much intuitive in Pagemaker or Quark. If you're going to have a user-hostile interface, at least have some decent documentation. Most of the hours I spend trying to figure things out are spent searching forums on the Web. However, doing decent documentation costs money. Adobe obviously has saved a lot of money here. I feel as if, if I'm ever going to reach any level of proficiency with this program, it's going to mean going to a training class. Now, that's great for independent trainers, not so great for me, since I'll have to pay for something that IMHO shouldn't be needed. You should perhaps need training to be a power user ... not to just figure out how to perform common operations. ljk ___ Deja Moo: The feeling that you've heard this bull before. Daniel Emory [EMAIL PROTECTED] Sent by: [EMAIL PROTECTED] 05/18/2006 02:16 PM To Framers List framers@FrameUsers.com cc Subject RE: Numbering Systems for Technical Service Manuals --- Anne Robotti [EMAIL PROTECTED] wrote: Is this a private email from Linda that you posted to the list? How completely rude. = My mistake, and I apologize to Linda. The Framer's list, unlike some others, identifies the sender's name, not the list's name as the sender. My default email setup only identifies the sender in the From line, thus, when I hit reply, only the sender's name appears in the To line. Since the thread originated on the Framers list, I presumptively added the list name on the cc line in my reply. I usually check first to see if that is proper, but this time I failed to do so. I'll be more careful in the future. My bad. Nevertheless, this issue about numbering of titled headings, tables and graphics seems to come up frequently. It's a valid issue, and it deserves more discussion on the list. And by the way, I do not apologize for describing most on-line help as shovelware. If that is offensive to some, so be it. The FrameMaker on-line help in versions 4 and earlier was far superior to the shovelware that replaced it in later versions. That, coupled with the much less complete printed manual, makes life more difficult for newbies. Many of the FrameMaker issues which come up over and over again on this list should be answered by declaring RTFM. Unfortuantely, that recommendation no longer applies in many cases. The same goes for the Acrobat manual. Dan Emory Associates FrameMaker/FrameMaker+SGML Document Design Database Publishing [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/laura_j_kirk%40bd.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. - ** IMPORTANT MESSAGE FOR RECIPIENTS IN THE U.S.A: This message may constitute an advertisement of BD group's products or services or a solicitation of interest in them. If this is such a message and you would like to opt out of receiving future advertisements or solicitations from this BD group, please forward this e-mail to the [EMAIL PROTECTED] ** This message (which includes any attachments) is intended only for the designated recipient(s). It may contain confidential or proprietary information and may be subject to attorney-client privilege or other confidentiality protections. If you are not a designated recipient, you may not review, use, copy or distribute this message. If you received this in error, please notify the sender by reply e-mail and delete this message. Thank You ** Corporate Headquarters Mailing Address: BD (Becton, Dickinson and Company) 1 Becton Drive Franklin Lakes, NJ 07417 U.S.A. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Numbering Systems for Technical Service Manuals
Excellent post Dan. Your post was exactly what I wanted (but was too lazy) to post as soon as I saw the original post about numbering. Far too often I see technical writers complaining about layout, format, or organisation because they simply don't like it or it doesn't look right. And then justifying their whole scale design changes on their limited exposure to one limited field of techwriting and techwriters. Anyone who will redesign a document or glibly dismiss existing standards or traditions simply for what looks better without researching the issue and reasons for the style or getting solid evidence the current usage either hinders production or user understanding without providing benefits to at least a subset of users doesn't really deserve the title of technical IMO. While technical documents need not forgo good design, they should not forgo function for the sake of design. Reluctantly submitting to the style guide and complaining it's only because the engineers want it that way is little better. As technical writers, we owe it to our audiences to understand their needs and requirements as well as the technical information we are trying to convey. Sometimes too, it requires the humility to understand that the system/layout you don't like may have no logical or relevant reason behind it, but not liking it is just as baseless a decision. In the event of conflicting arbitrary decisions, continuing with the current standard for consistency is usually the way to go. So, if you want to make a change, you need not prove the previous method wrong, but prove the new method superior. Daniel Emory wrote on 05/17/2006 10:36:11 PM: Even relatively simple on-line help docs should have some sort of numbering scheme. Typically, users who can't figure out something from the on-line help will resort to a customer help line or in-house expert. If the user can give the help specialist the number of the particular on-line help content where the user is stuck, ambiguity is eliminated, a successful resolution of the problem is more likely, and the time to arrive at the correct solution is likely to be minimized. Too true. If the numbers wouldn't describe structure, even a random number (the internal help topic number?) that could be made visible would make referencing, commenting, and updating the system much simpler. Or, in my experience, the user may be able to stop travelling a circular path of references a little sooner if the organisational structure of the help file was more apparent. Perhaps the numbering may even avoid confusion between two similar yet subtly different topics. Eric L. Dunn Senior Technical Writer ___ This e-mail communication (and any attachment/s) may contain confidential or privileged information and is intended only for the individual(s) or entity named above and to others who have been specifically authorized to receive it. If you are not the intended recipient, please do not read, copy, use or disclose the contents of this communication to others. Please notify the sender that you have received this e-mail in error by reply e-mail, and delete the e-mail subsequently. Please note that in order to protect the security of our information systems an AntiSPAM solution is in use and will browse through incoming emails. Thank you. _ Ce message (ainsi que le(s) fichier/s), transmis par courriel, peut contenir des renseignements confidentiels ou protégés et est destiné à l?usage exclusif du destinataire ci-dessus. Toute autre personne est par les présentes avisée qu?il est strictement interdit de le diffuser, le distribuer ou le reproduire. Si vous l?avez reçu par inadvertance, veuillez nous en aviser et détruire ce message. Veuillez prendre note qu'une solution antipollupostage (AntiSPAM) est utilisée afin d'assurer la sécurité de nos systems d'information et qu'elle furètera les courriels entrant. Merci. _ (See attached file: C.htm) brfont size=2 face=sans-serifExcellent post Dan. Your post was exactly what I wanted (but was too lazy) to post as soon as I saw the original post about numbering./font br brfont size=2 face=sans-serifFar too often I see quot;technicalquot; writers complaining about layout, format, or organisation because they simply quot;don't like itquot; or quot;it doesn't look rightquot;. And then justifying their whole scale design changes on their limited exposure to one limited field of techwriting and techwriters./font br brfont size=2 face=sans-serifAnyone who will redesign a document or glibly dismiss existing standards or traditions simply for what quot;looks betterquot; without researching the issue and reasons
Numbering Systems for Technical Service Manuals
--- "Linda G. Gallagher" wrote: > I don't think it was necessary to single out my > response and call what I > said laughable. Your unqualified statement that the only people left who use such numbering schemes are engineers communicating with other engineers is what made it laughable, because your statement itself was insulting to the many technical disciplines where such numbering schemes are considered essential. Clearly, many types of technical documentation other than engineer-to-engineer documents are enhanced by using a rational numbering scheme, and I cited many examples in my initial reply. One could infer that your conclusion derives from the fact that your millieu is restricted to on-line help--the realm where shovelware reigns supreme. In general, that regime only works when the product being supported is some relatively simple piece of software, and on-line help is only useful to beginners, who would probably be better off if they could print a complete manual that actually looks like a technical manual when it is printed. The general assumption of on-line help developers seems to be that links are a substitute for a rational numbering scheme. You may be surprised to learn that there are vast realms in which selected technical manual content must be printed out in order to successfully carry out tasks, and thus links no longer work. in those cases, a rational numbering scheme in the printed portion replaces links as the method for finding (and printing) referenced content. That's an unnecessary insult. == Your statement itself insulted those who produce technical content that is far superior to the typical on-line help shovelware. == > As for this particular issue, I know of few writers > and companies who advocate using numbered sections as you suggest. == How many companies or writers do you know who work outside the realm of on-line help shovelware? Dan Emory & Associates FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Numbering Systems for Technical Service Manuals
Is this a private email from Linda that you posted to the list? How completely rude. *That* is surely a netiquette violation, I've never been on an email list or newsgroup where it was tolerated. Anne > -Original Message- > From: > framers-bounces+arobotti=journalregister.com at lists.frameusers. > com > [mailto:framers-bounces+arobotti=journalregister.com at lists.fra meusers.com] On Behalf Of Daniel Emory > Sent: Thursday, May 18, 2006 11:31 AM > To: lindag at techcomplus.com > Cc: Framers List > Subject: RE: Numbering Systems for Technical Service Manuals > > --- "Linda G. Gallagher" > wrote: > > I don't think it was necessary to single out my response > and call what > > I said laughable. The information contained in or attached to this e-mail contains confidential or privileged information. If you are not the intended recipient, be aware that any disclosure, copying, distribution or use of the contents of this e-mail is PROHIBITED. If you have received this e-mail in error, please notify the sender and delete the e-mail immediately. Thank you.
Numbering Systems for Technical Service Manuals
--- Anne Robotti wrote: > Is this a private email from Linda that you posted > to the list? How > completely rude. = My mistake, and I apologize to Linda. The Framer's list, unlike some others, identifies the sender's name, not the list's name as the sender. My default email setup only identifies the sender in the From line, thus, when I hit reply, only the sender's name appears in the To line. Since the thread originated on the Framers list, I presumptively added the list name on the cc line in my reply. I usually check first to see if that is proper, but this time I failed to do so. I'll be more careful in the future. My bad. Nevertheless, this issue about numbering of titled headings, tables and graphics seems to come up frequently. It's a valid issue, and it deserves more discussion on the list. And by the way, I do not apologize for describing most on-line help as shovelware. If that is offensive to some, so be it. The FrameMaker on-line help in versions 4 and earlier was far superior to the shovelware that replaced it in later versions. That, coupled with the much less complete printed manual, makes life more difficult for newbies. Many of the FrameMaker issues which come up over and over again on this list should be answered by declaring RTFM. Unfortuantely, that recommendation no longer applies in many cases. The same goes for the Acrobat manual. Dan Emory & Associates FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Numbering Systems for Technical Service Manuals
I'm not familiar with versions of FM help prior to vers. 7, which I am using. That, I can agree wholeheartedly, sucks. As a self-taught FM user, it takes hours, literally hours to figure out some new operation or feature in Framemaker. Operations/features, I might add, that were pretty much intuitive in Pagemaker or Quark. If you're going to have a user-hostile interface, at least have some decent documentation. Most of the hours I spend trying to figure things out are spent searching forums on the Web. However, doing decent documentation costs money. Adobe obviously has saved a lot of money here. I feel as if, if I'm ever going to reach any level of proficiency with this program, it's going to mean going to a training class. Now, that's great for independent trainers, not so great for me, since I'll have to pay for something that IMHO shouldn't be needed. You should perhaps need training to be a "power user" ... not to just figure out how to perform common operations. ljk ___ Deja Moo: The feeling that you've heard this bull before. Daniel Emory Sent by: framers-bounces+laura_j_kirk=bd.com at lists.frameusers.com 05/18/2006 02:16 PM To Framers List cc Subject RE: Numbering Systems for Technical Service Manuals --- Anne Robotti wrote: > Is this a private email from Linda that you posted > to the list? How > completely rude. = My mistake, and I apologize to Linda. The Framer's list, unlike some others, identifies the sender's name, not the list's name as the sender. My default email setup only identifies the sender in the From line, thus, when I hit reply, only the sender's name appears in the To line. Since the thread originated on the Framers list, I presumptively added the list name on the cc line in my reply. I usually check first to see if that is proper, but this time I failed to do so. I'll be more careful in the future. My bad. Nevertheless, this issue about numbering of titled headings, tables and graphics seems to come up frequently. It's a valid issue, and it deserves more discussion on the list. And by the way, I do not apologize for describing most on-line help as shovelware. If that is offensive to some, so be it. The FrameMaker on-line help in versions 4 and earlier was far superior to the shovelware that replaced it in later versions. That, coupled with the much less complete printed manual, makes life more difficult for newbies. Many of the FrameMaker issues which come up over and over again on this list should be answered by declaring RTFM. Unfortuantely, that recommendation no longer applies in many cases. The same goes for the Acrobat manual. Dan Emory & Associates FrameMaker/FrameMaker+SGML Document Design & Database Publishing ___ You are currently subscribed to Framers as Laura_J_Kirk at bd.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/laura_j_kirk%40bd.com Send administrative questions to lisa at frameusers.com. Visit http://www.frameusers.com/ for more resources and info. - ** IMPORTANT MESSAGE FOR RECIPIENTS IN THE U.S.A: This message may constitute an advertisement of BD group's products or services or a solicitation of interest in them. If this is such a message and you would like to opt out of receiving future advertisements or solicitations from this BD group, please forward this e-mail to the optoutbygroup at bd.com. ** This message (which includes any attachments) is intended only for the designated recipient(s). It may contain confidential or proprietary information and may be subject to attorney-client privilege or other confidentiality protections. If you are not a designated recipient, you may not review, use, copy or distribute this message. If you received this in error, please notify the sender by reply e-mail and delete this message. Thank You ** Corporate Headquarters Mailing Address: BD (Becton, Dickinson and Company) 1 Becton Drive Franklin Lakes, NJ 07417 U.S.A.
"Intuitive software" WAS: Numbering Systems for Technical Service Manuals
Hi, Laura: At 3:08 PM -0400 5/18/06, Laura_J_Kirk at bd.com wrote: >I'm not familiar with versions of FM help prior to vers. 7, which I am >using. That, I can agree wholeheartedly, sucks. > >As a self-taught FM user, it takes hours, literally hours to figure out >some new operation or feature in Framemaker. Operations/features, I might >add, that were pretty much intuitive in Pagemaker or Quark. If you're >going to have a user-hostile interface, at least have some decent >documentation. Most of the hours I spend trying to figure things out are >spent searching forums on the Web. I've been an independent FrameMaker trainer and user since FrameMaker 2.x. If you mean by "intuitive," "everything I used to know falls into place in new environments," then there's no surprise that you're disappointed in finding that your PageMaker and QuarkXPress skills and experience don't fit right into FrameMaker. I've found that usually "intuitive" means "familiar." Yes, FrameMaker's interface is different from other tools. However, if you cruise the InDesign forums, and probably Apple's Pages forums, and perhaps MS's Publisher's, and Ventura Publisher's, you'd probably find the same new-user frustrations voiced by those who are having "culture clash" when they first encounter the new tools. FrameMaker's features and operations are highly consistent, so what you do learn in one area usually helps you pick up speed as you enter new areas. If you total the number of hours you've spent independently searching for solutions and multiply them by your average hourly pay, you'll have something concrete to help you compare to the cost of training you might have taken. >However, doing decent documentation costs money. Adobe obviously has saved >a lot of money here. I feel as if, if I'm ever going to reach any level of >proficiency with this program, it's going to mean going to a training >class. Now, that's great for independent trainers, not so great for me, >since I'll have to pay for something that IMHO shouldn't be needed. You >should perhaps need training to be a "power user" ... not to just figure >out how to perform common operations. One of the key misunderstandings about FrameMaker and other publishing tools in its class (yes there are a few), is that they combine the skill sets that used to be performed by as many as six or seven separate professionals into the one job description of "technical author." If you list all the tasks that you've faced as a technical author so far, and those that you expect to face, you'll probably see that nearly everything on the long list is within FrameMaker's capabilities. In my view, the job is what's hard and not necessarily intuitive; FrameMaker is just the tool that you use to do the job. In addition to Adobe's FrameMaker documentation, the Classroom In A Book is a useful learning tool (though there are some errors that can "throw" you off), and FrameMaker 7: The Complete Reference, are among supplementary learning resources you can use on your own. You'll find a bunch in a Google search or two. >ljk >___ >Deja Moo: The feeling that you've heard this bull before. This is how I usually feel about criticisms of something for being "non-intuitive," when it's really "not familiar." Regards, Peter Gold KnowHow ProServices Adobe Certified Expert FrameMaker - Acrobat - InDesign
Numbering Systems for Technical Service Manuals
Excellent post Dan. Your post was exactly what I wanted (but was too lazy) to post as soon as I saw the original post about numbering. Far too often I see "technical" writers complaining about layout, format, or organisation because they simply "don't like it" or "it doesn't look right". And then justifying their whole scale design changes on their limited exposure to one limited field of techwriting and techwriters. Anyone who will redesign a document or glibly dismiss existing standards or traditions simply for what "looks better" without researching the issue and reasons for the style or getting solid evidence the current usage either hinders production or user understanding without providing benefits to at least a subset of users doesn't really deserve the title of "technical" IMO. While technical documents need not forgo good design, they should not forgo function for the sake of design. Reluctantly submitting to the style guide and complaining it's only "because the engineers want it that way" is little better. As technical writers, we owe it to our audiences to understand their needs and requirements as well as the technical information we are trying to convey. Sometimes too, it requires the humility to understand that the system/layout you don't like may have no logical or relevant reason behind it, but not liking it is just as baseless a decision. In the event of conflicting arbitrary decisions, continuing with the current standard for consistency is usually the way to go. So, if you want to make a change, you need not prove the previous method wrong, but prove the new method superior. Daniel Emory wrote on 05/17/2006 10:36:11 PM: > Even relatively simple on-line help docs should have > some sort of numbering scheme. Typically, users who > can't figure out something from the on-line help will > resort to a customer help line or in-house expert. If > the user can give the help specialist the number of > the particular on-line help content where the user is > stuck, ambiguity is eliminated, a successful > resolution of the problem is more likely, and the time > to arrive at the correct solution is likely to be > minimized. Too true. If the numbers wouldn't describe structure, even a random number (the internal help topic number?) that could be made visible would make referencing, commenting, and updating the system much simpler. Or, in my experience, the user may be able to stop travelling a circular path of references a little sooner if the organisational structure of the help file was more apparent. Perhaps the numbering may even avoid confusion between two similar yet subtly different topics. Eric L. Dunn Senior Technical Writer ___ This e-mail communication (and any attachment/s) may contain confidential or privileged information and is intended only for the individual(s) or entity named above and to others who have been specifically authorized to receive it. If you are not the intended recipient, please do not read, copy, use or disclose the contents of this communication to others. Please notify the sender that you have received this e-mail in error by reply e-mail, and delete the e-mail subsequently. Please note that in order to protect the security of our information systems an AntiSPAM solution is in use and will browse through incoming emails. Thank you. _ Ce message (ainsi que le(s) fichier/s), transmis par courriel, peut contenir des renseignements confidentiels ou prot?g?s et est destin? ? l?usage exclusif du destinataire ci-dessus. Toute autre personne est par les pr?sentes avis?e qu?il est strictement interdit de le diffuser, le distribuer ou le reproduire. Si vous l?avez re?u par inadvertance, veuillez nous en aviser et d?truire ce message. Veuillez prendre note qu'une solution antipollupostage (AntiSPAM) est utilis?e afin d'assurer la s?curit? de nos systems d'information et qu'elle fur?tera les courriels entrant. Merci. _ (See attached file: C.htm) -- next part -- An embedded and charset-unspecified text was scrubbed... Name: C.htm Url: http://lists.frameusers.com/pipermail/framers/attachments/20060518/c40fe88f/attachment.ksh
RE: Numbering Systems for Technical Service Manuals
I still use the numeric outline form for all the large documents. We often go down 3 or 4 levels below the chapter, and the numbering makes it clear where we are. Nancy Carpenter Lead Technical Writer GENCO Distribution System 100 Papercraft Park Pittsburgh, Pennsylvania 15238 |-+--- | | Linda G. Gallagher| | | [EMAIL PROTECTED]| | | Sent by:| | | [EMAIL PROTECTED]| | | meusers.com | | | | | | | | | 05/16/2006 05:57 PM | | | Please respond to lindag| | | | |-+--- --| | | | To: Gillian Flato [EMAIL PROTECTED], framers@frameusers.com | | cc: | | Subject: RE: Numbering Systems for Technical Service Manuals | --| I only use that type of numbering when a client insists on it. Typically, those clients are engineers with content targeting other engineers. ~~ Linda G. Gallagher TechCom Plus, LLC Intelligent technical communication since 1993 Technical writing, help development, FrameMaker and WebWorks Publisher conversions [EMAIL PROTECTED] http://www.techcomplus.com/ 303-450-9076 800-500-3144 ~~ Manager, Consulting and Independent Contracting Special Interest Group Society for Technical Communication http://www.stcsig.org/cic/index.html ~~ -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] Behalf Of Gillian Flato Sent: Tuesday, May 16, 2006 1:09 PM To: framers@frameusers.com Subject: Numbering Systems for Technical Service Manuals Guys, When you write a Technical Manual do you number heads and sections with 1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and it's numbered that way. It looks very cluttered to me. By taking that out and using conventional styles, it has an easier UI to me. What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * [EMAIL PROTECTED] blocked::mailto:[EMAIL PROTECTED] This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/lindag%40techcomplus.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/carpentn%40genco.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Numbering Systems for Technical Service Manuals
I still use the numeric outline form for all the large documents. We often
go down 3 or 4 levels below the chapter, and the numbering makes it clear
where we are.
Nancy Carpenter
Lead Technical Writer
GENCO Distribution System
100 Papercraft Park
Pittsburgh, Pennsylvania 15238
|-+--->
| | "Linda G. Gallagher"|
| | |
| | Sent by:|
| | framers-bounces+carpentn=genco.com at lists.fra|
| | meusers.com |
| | |
| | |
| | 05/16/2006 05:57 PM |
| | Please respond to lindag|
| | |
|-+--->
>--|
|
|
| To: "Gillian Flato" ,|
| cc:
|
| Subject: RE: Numbering Systems for Technical Service Manuals
|
>--|
I only use that type of numbering when a client insists on it. Typically,
those clients are engineers with content targeting other engineers.
~~
Linda G. Gallagher
TechCom Plus, LLC
Intelligent technical communication since 1993
Technical writing, help development,
FrameMaker and WebWorks Publisher conversions
lindag at techcomplus.com
http://www.techcomplus.com/
303-450-9076
800-500-3144
~~
Manager, Consulting and Independent Contracting
Special Interest Group
Society for Technical Communication
http://www.stcsig.org/cic/index.html
~~
-Original Message-
From: framers-bounces+lindag=techcomplus@lists.frameusers.com
[mailto:framers-bounces+lindag=techcomplus.com at lists.frameusers.com]On
Behalf Of Gillian Flato
Sent: Tuesday, May 16, 2006 1:09 PM
To: framers at frameusers.com
Subject: Numbering Systems for Technical Service Manuals
Guys,
When you write a Technical Manual do you number heads and sections with
1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and
it's numbered that way. It looks very cluttered to me. By taking that
out and using conventional styles, it has an easier UI to me.
What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type
of way? Is that generally history now, or is it actually still used a
lot?
Thanks,
Gillian Flato
Technical Writer (Software)
NANOmetrics, Inc.
1550 Buckeye Dr.
Milpitas, CA. 95035
(408.435.9600 x 316
7 408.232.5911
* gflato at nanometrics.com
This message (including any attachments) may contain confidential
information intended for a specific individual and purpose. If you are not
the intended recipient, delete this message. If you are not the intended
recipient, disclosing, copying, distributing, or taking any action based on
this message is strictly prohibited.
___
You are currently subscribed to Framers as lindag at techcomplus.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/lindag%40techcomplus.com
Send administrative questions to lisa at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
___
You are currently subscribed to Framers as carpentn at genco.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/carpentn%40genco.com
Send administrative questions to lisa at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
Numbering Systems for Technical Service Manuals
--- "Linda G. Gallagher" wrote: > I only use that type of numbering when a client > insists on it. Typically, > those clients are engineers with content targeting > other engineers. == The complaint that prompted Ms. Gallagher's response was that multi-level numbering schemes "looked clunky," the implication being that such numbering offended the writer's esthetic sensibilities. Ms. Gallagher's response is a laughable explanation for when (or why) multi-level numbering of topics (as well as tables and graphics) might be necessary. No doubt most engineers use such numbering schemes because it is the only assured way to avoid ambiguity when you reference something. The legal profession uses such numbering schemes for the same reason. Then there are the military and the Air Trasport Association (ATA) (among many others) which also require such numbering schemes because a number provides a way to double-check that that the user is following the correct procedure. Someone else pointed out (correctly) that the concept of a content management system (CMS) also imposes a requirement for such numbering schemes in order to facilitate the retrieval from a CMS of the particular information needed by a user. To implement this, the value of each level of a multi-level number appears in a separate attribute (ala ATA DTDs, where the attributes are named Chapter, Section, Subject, Page Block, Task, and Subtask). Inspection Work Cards in the ATA system identify the applicable number(s) associated with each task or subtask identified on an individual work card. If the inspection results in the need for some corrective action, the multi-level task number specified on the work card is used to retrieve that task from the CMS. The user can then verify that the number on the delivered content matches the number specified on the work card for that task. This process of number re-verification is an essential ingredient of a zero-tolerance maintenance environment. Producing technical manuals of any substantial size and scope demands an appropriate multi-level numbering scheme, not just for titled text, but also for titled tables and graphics. Even relatively simple on-line help docs should have some sort of numbering scheme. Typically, users who can't figure out something from the on-line help will resort to a customer help line or in-house expert. If the user can give the help specialist the number of the particular on-line help content where the user is stuck, ambiguity is eliminated, a successful resolution of the problem is more likely, and the time to arrive at the correct solution is likely to be minimized. Dan Emory & Associates FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Numbering Systems for Technical Service Manuals
Guys, When you write a Technical Manual do you number heads and sections with 1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and it's numbered that way. It looks very cluttered to me. By taking that out and using conventional styles, it has an easier UI to me. What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * [EMAIL PROTECTED] blocked::mailto:[EMAIL PROTECTED] This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Numbering Systems for Technical Service Manuals
I think it's still mostly used in environments where the manuals are written to a standard that requires it: MilSpec, BellCore, whatever In civilian docs, I think it's largely faded away. Art On 5/16/06, Gillian Flato [EMAIL PROTECTED] wrote: Guys, snip What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? -- Art Campbell [EMAIL PROTECTED] ... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl. -- Richard Thompson No disclaimers apply. DoD 358 ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Numbering Systems for Technical Service Manuals
I think you are right Art. The basic reason for this structure was to enable easy reference/navigation to specific entries. As we move further away from dead tree versions, the need for this kind of user-observable structuring is fading. OTOH, I think one could argue that the rise of XML and other markup languages is incresing the demand for this kind (as in nature) of item marking is becoming ever more prevalent. Grant What makes a master is not physical skill alone but mental clarity, emotional maturity, and spiritual awareness. --Tom Callos -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Art Campbell Sent: Tuesday, May 16, 2006 1:20 PM To: Gillian Flato Cc: framers@frameusers.com Subject: Re: Numbering Systems for Technical Service Manuals I think it's still mostly used in environments where the manuals are written to a standard that requires it: MilSpec, BellCore, whatever In civilian docs, I think it's largely faded away. Art On 5/16/06, Gillian Flato [EMAIL PROTECTED] wrote: Guys, snip What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? -- Art Campbell [EMAIL PROTECTED] ... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl. -- Richard Thompson No disclaimers apply. DoD 358 ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Numbering Systems for Technical Service Manuals
I do number, but never below a fourth level (1.2.3.4). I am not required to do so by spec or policy. I personally find when I read long manuals (e.g. a camcorder, digital camera, etc.) that when it is not numbered, I do not assimilate data as well because I lose the hierarchy of information. I need a structure into which to save information. Thus, for my readers who may be similarly wired, I number the paragraphs. For those who don't need numbering, I doubt any find their understanding of the material to be harmed by the presence of paragraph numbers. So it seems, pretty much, win-win to use para. numbering. The one exception was a manual that we were submitting for a CLIA waiver. It had to be written to a 7th grade level, and I used exaggerated font size changes to indicate paragraph levels (e.g. top level was 48 pt., second level was 24 pt., third level was 14 pt., and there was no fourth level). ljk ___ Deja Moo: The feeling that you've heard this bull before. Gillian Flato [EMAIL PROTECTED] Sent by: [EMAIL PROTECTED] 05/16/2006 03:09 PM To framers@frameusers.com cc Subject Numbering Systems for Technical Service Manuals Guys, When you write a Technical Manual do you number heads and sections with 1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and it's numbered that way. It looks very cluttered to me. By taking that out and using conventional styles, it has an easier UI to me. What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * [EMAIL PROTECTED] blocked::mailto:[EMAIL PROTECTED] This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/laura_j_kirk%40bd.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. - ** IMPORTANT MESSAGE FOR RECIPIENTS IN THE U.S.A: This message may constitute an advertisement of BD group's products or services or a solicitation of interest in them. If this is such a message and you would like to opt out of receiving future advertisements or solicitations from this BD group, please forward this e-mail to the [EMAIL PROTECTED] ** This message (which includes any attachments) is intended only for the designated recipient(s). It may contain confidential or proprietary information and may be subject to attorney-client privilege or other confidentiality protections. If you are not a designated recipient, you may not review, use, copy or distribute this message. If you received this in error, please notify the sender by reply e-mail and delete this message. Thank You ** Corporate Headquarters Mailing Address: BD (Becton, Dickinson and Company) 1 Becton Drive Franklin Lakes, NJ 07417 U.S.A. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Numbering Systems for Technical Service Manuals
Guys, When you write a Technical Manual do you number heads and sections with 1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and it's numbered that way. It looks very cluttered to me. By taking that out and using conventional styles, it has an easier UI to me. What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * gflato at nanometrics.com This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited.
Numbering Systems for Technical Service Manuals
I think it's still mostly used in environments where the manuals are written to a standard that requires it: MilSpec, BellCore, whatever In "civilian" docs, I think it's largely faded away. Art On 5/16/06, Gillian Flato wrote: > Guys, > What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type > of way? Is that generally history now, or is it actually still used a > lot? -- 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
Numbering Systems for Technical Service Manuals
I think you are right Art. The basic reason for this structure was to enable easy reference/navigation to specific entries. As we move further away from "dead tree" versions, the need for this kind of user-observable structuring is fading. OTOH, I think one could argue that the rise of XML and other markup languages is incresing the demand for this kind (as in "nature") of item marking is becoming ever more prevalent. Grant "What makes a master is not physical skill alone but mental clarity, emotional maturity, and spiritual awareness." --Tom Callos -Original Message- From: framers-bounces+grant.hogarth=reuters@lists.frameusers.com [mailto:framers-bounces+grant.hogarth=reuters.com at lists.frameusers.com] On Behalf Of Art Campbell Sent: Tuesday, May 16, 2006 1:20 PM To: Gillian Flato Cc: framers at frameusers.com Subject: Re: Numbering Systems for Technical Service Manuals I think it's still mostly used in environments where the manuals are written to a standard that requires it: MilSpec, BellCore, whatever In "civilian" docs, I think it's largely faded away. Art On 5/16/06, Gillian Flato wrote: > Guys, > What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 > type of way? Is that generally history now, or is it actually still > used a lot? -- 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
Numbering Systems for Technical Service Manuals
I do number, but never below a fourth level (1.2.3.4). I am not required to do so by spec or policy. I personally find when I read long manuals (e.g. a camcorder, digital camera, etc.) that when it is not numbered, I do not assimilate data as well because I lose the hierarchy of information. I need a structure into which to save information. Thus, for my readers who may be similarly wired, I number the paragraphs. For those who don't need numbering, I doubt any find their understanding of the material to be harmed by the presence of paragraph numbers. So it seems, pretty much, win-win to use para. numbering. The one exception was a manual that we were submitting for a CLIA waiver. It had to be written to a 7th grade level, and I used exaggerated font size changes to indicate paragraph levels (e.g. top level was 48 pt., second level was 24 pt., third level was 14 pt., and there was no fourth level). ljk ___ Deja Moo: The feeling that you've heard this bull before. "Gillian Flato" Sent by: framers-bounces+laura_j_kirk=bd.com at lists.frameusers.com 05/16/2006 03:09 PM To cc Subject Numbering Systems for Technical Service Manuals Guys, When you write a Technical Manual do you number heads and sections with 1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and it's numbered that way. It looks very cluttered to me. By taking that out and using conventional styles, it has an easier UI to me. What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * gflato at nanometrics.com This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited. ___ You are currently subscribed to Framers as Laura_J_Kirk at bd.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/laura_j_kirk%40bd.com Send administrative questions to lisa at frameusers.com. Visit http://www.frameusers.com/ for more resources and info. - ** IMPORTANT MESSAGE FOR RECIPIENTS IN THE U.S.A: This message may constitute an advertisement of BD group's products or services or a solicitation of interest in them. If this is such a message and you would like to opt out of receiving future advertisements or solicitations from this BD group, please forward this e-mail to the optoutbygroup at bd.com. ** This message (which includes any attachments) is intended only for the designated recipient(s). It may contain confidential or proprietary information and may be subject to attorney-client privilege or other confidentiality protections. If you are not a designated recipient, you may not review, use, copy or distribute this message. If you received this in error, please notify the sender by reply e-mail and delete this message. Thank You ** Corporate Headquarters Mailing Address: BD (Becton, Dickinson and Company) 1 Becton Drive Franklin Lakes, NJ 07417 U.S.A.
Numbering Systems for Technical Service Manuals
I only use that type of numbering when a client insists on it. Typically, those clients are engineers with content targeting other engineers. ~~ Linda G. Gallagher TechCom Plus, LLC Intelligent technical communication since 1993 Technical writing, help development, FrameMaker and WebWorks Publisher conversions lindag at techcomplus.com http://www.techcomplus.com/ 303-450-9076 800-500-3144 ~~ Manager, Consulting and Independent Contracting Special Interest Group Society for Technical Communication http://www.stcsig.org/cic/index.html ~~ -Original Message- From: framers-bounces+lindag=techcomplus@lists.frameusers.com [mailto:framers-bounces+lindag=techcomplus.com at lists.frameusers.com]On Behalf Of Gillian Flato Sent: Tuesday, May 16, 2006 1:09 PM To: framers at frameusers.com Subject: Numbering Systems for Technical Service Manuals Guys, When you write a Technical Manual do you number heads and sections with 1.1, 1.2, 1.2.1 etc. I have a manual which is essentially an API and it's numbered that way. It looks very cluttered to me. By taking that out and using conventional styles, it has an easier UI to me. What's the general consensus on numbering with the 1.1, 1.1.1, 1.2 type of way? Is that generally history now, or is it actually still used a lot? Thanks, Gillian Flato Technical Writer (Software) NANOmetrics, Inc. 1550 Buckeye Dr. Milpitas, CA. 95035 (408.435.9600 x 316 7 408.232.5911 * gflato at nanometrics.com This message (including any attachments) may contain confidential information intended for a specific individual and purpose. If you are not the intended recipient, delete this message. If you are not the intended recipient, disclosing, copying, distributing, or taking any action based on this message is strictly prohibited. ___ You are currently subscribed to Framers as lindag at techcomplus.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/lindag%40techcomplus.com Send administrative questions to lisa at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
