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.
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.
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
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.
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.
