Re: Off topic - three general documentation questions
Did you ever hear about duplex printing? ;-) Bodvar Bjorgvinsson 2009/3/17 Bill Swallow techcommd...@gmail.com: Why on earth would you have blank PDF page? Who's going to take it, print it, and bind it, and then use only the printout? -- Bill Swallow Twitter: @techcommdood Blog: http://techcommdood.com LinkedIn: http://www.linkedin.com/in/techcommdood ___ You are currently subscribed to Framers as bod...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/bodvar%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. -- It is impossible to make anything foolproof because fools are so ingenious. -- Edsel Murphy, dec. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Three general documentation questions
Ian Saunders wrote: My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. For the first two issues, I'd recommend that you adopt a style manual for your organization. Every organization has a few house rules that go against the style manual, but hopefully they are few. I'd recommend either the Chicago Manual of Style, or the Microsoft Manual of Style for Technical Publications, Third Edition. Both are good and will likely address these issues. (Ok, and just from me, those first two issues seem ill-advised and non-standard.) On the blank pages issue, it depends on the most common use model for your PDFs. If you expect someone to print them out on a 2-sided printer, it makes sense for the blanks to be there. If you expect your reader to read online or print on a 1-sided printer, I'd vote to take the blanks out. I don't see a problem with blanks, and I hate This page intentionally left blank. Tina Ricks | Editor | Trial Guides t...@trialguides.com www.trialguides.com ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Off topic - three general documentation questions
Did you ever hear about duplex printing? ;-) Bodvar Bjorgvinsson 2009/3/17 Bill Swallow : > > Why on earth would you have blank PDF page? Who's going to take it, > print it, and bind it, and then use only the printout? > > -- > Bill Swallow > Twitter: @techcommdood > Blog: http://techcommdood.com > LinkedIn: http://www.linkedin.com/in/techcommdood > ___ > > > You are currently subscribed to Framers as bodvar at gmail.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/bodvar%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. > -- "It is impossible to make anything foolproof because fools are so ingenious." -- Edsel Murphy, dec.
Three general documentation questions
Ian Saunders wrote: My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. For the first two issues, I'd recommend that you adopt a style manual for your organization. Every organization has a few house rules that go against the style manual, but hopefully they are few. I'd recommend either the Chicago Manual of Style, or the Microsoft Manual of Style for Technical Publications, Third Edition. Both are good and will likely address these issues. (Ok, and just from me, those first two issues seem ill-advised and non-standard.) On the blank pages issue, it depends on the most common use model for your PDFs. If you expect someone to print them out on a 2-sided printer, it makes sense for the blanks to be there. If you expect your reader to read online or print on a 1-sided printer, I'd vote to take the blanks out. I don't see a problem with blanks, and I hate "This page intentionally left blank." Tina Ricks | Editor | Trial Guides tina at trialguides.com www.trialguides.com
Re: Off topic - three general documentation questions
Ian, In general, from a professional tech writer viewpoint, I think the first two ideas suck, but to go a little further, you didn't really provide enough info: * what is the goal of the redo? * what standard or style guide are you following that presents these suggestions, or which are you going to follow? * what audience do you write to * what kind of guides are you producing? Software / hardware, installation, administration, user, something else? As for the third idea, why have blank pages in a PDF at all? If it's so people can print a book traditional fashion... that may be the real question -- if that's useful, or required, or something else. In any case, I'd simply eliminate the blanks before I labeled them unless they are required AND a label is required by a standard. Cheers, Art Art Campbell art.campb...@gmail.com ... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl. -- Richard Thompson No disclaimers apply. DoD 358 On Fri, Mar 13, 2009 at 5:45 AM, Saunders, Ian isaund...@syntellect.com wrote: Please forgive this off-topic query, but I have nowhere else to turn for help. My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. We have reached an impasse... I would be extremely grateful to anyone who can supply their take on the relevant industry standards or maybe even point me at a definitive statement. Many thanks! Ian Saunders Syntellect Inc ___ You are currently subscribed to Framers as art.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Off topic - three general documentation questions
Here are my thoughts based on my deliverables, my users' needs, and my employer's expectations. Your responses may vary significantly based on those and other variables. * Do not use chapter numbers/appendix letters I use chapter numbers in my printed books and PDFs, but not in online help. IMO they serve a valuable navigation function for the reader of a printed doc, helping to keep his/her bearings in the mass of pages. * Begin main index entries with a capital letter I would not, partly because an index entry is not a sentence and the capitalization might imply a meaning that does not exist, but also because it is much quicker to make an index entry by simply double-clicking the term without having to edit it on the spot. Of course, you still have to edit it if it starts a sentence or is capitalized for any other reason, but that is not so often. * Put a logo (or message) on blank pages to show that they are not blank in error. Because I print my books, I have all my chapters end on an even page, even if it is blank. My header and footer appear on those otherwise blank pages. The only time I get a question about it is when someone reads the PDF and comes upon a blank page for no obvious reason. Honestly, in 10 years with these templates the confusion has been brought to my attention maybe 6 times. Ymmv, etc, etc john -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Saunders, Ian Sent: Friday, March 13, 2009 5:45 AM To: framers@lists.frameusers.com Subject: Off topic - three general documentation questions Please forgive this off-topic query, but I have nowhere else to turn for help. My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. We have reached an impasse... I would be extremely grateful to anyone who can supply their take on the relevant industry standards or maybe even point me at a definitive statement. Many thanks! Ian Saunders Syntellect Inc ___ You are currently subscribed to Framers as jsgamm...@imprivata.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/jsgammato%40imprivat a.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Off topic - three general documentation questions
Put a logo (or message) on blank pages to show that they are not blank in error. This is an accepted standard across most of the DoD landscape. The phrase This page left intentionally blank is used. Regards, DJ -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Saunders, Ian Sent: Friday, March 13, 2009 5:45 AM To: framers@lists.frameusers.com Subject: Off topic - three general documentation questions Please forgive this off-topic query, but I have nowhere else to turn for help. My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. We have reached an impasse... I would be extremely grateful to anyone who can supply their take on the relevant industry standards or maybe even point me at a definitive statement. Many thanks! Ian Saunders Syntellect Inc ___ You are currently subscribed to Framers as darren.butler@robins.af.mil. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/darren.butler.ctr%40 robins.af.mil Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Off topic - three general documentation questions
My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. Regarding index entries, _The Chicago Manual of Style_ states: 18.10 Initial lowercase letters in main headings. The first word of a main heading is normally capitalized only if capitalized in text-- a proper noun, a genus name, the title of a work, and so on. Indexes in the sciences often avoid initial capitals because the distinction between capitalized and lowercased terms in the text may be crucial. Traditionally, all main headings in an index were capitalized; Chicago recommends the practice only where the subentries are so numerous that capitalized main headings make for easier navigation. The CMOS is a great reference to have on hand. It always seems to have the answers. Mike Wickham ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Off topic - three general documentation questions
* Do not use chapter numbers/appendix letters Neither here nor there. Sometimes it's easier to reference by a single char, but ultimately this is a PDF and is searchable with a dynamic TOC. * Begin main index entries with a capital letter Meh. Style issue. Let those who bark loudest win and then hold them to the convention. * Put a logo (or message) on blank pages to show that they are not blank in error. Why on earth would you have blank PDF page? Who's going to take it, print it, and bind it, and then use only the printout? -- Bill Swallow Twitter: @techcommdood Blog: http://techcommdood.com LinkedIn: http://www.linkedin.com/in/techcommdood ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Off topic - three general documentation questions
* Put a logo (or message) on blank pages to show that they are not blank in error. Why on earth would you have blank PDF page? Who's going to take it, print it, and bind it, and then use only the printout? *** I very seldom read any serious documentation online. When I am on the computer, I am productive in other ways. If the PDF is not printer-friendly, I will think it was put together by a rookie. PDFs are suitable for printing, until you screw it up. ymmv john ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Off topic - three general documentation questions
Interesting. When I'm on the computer, I'm all over the Help and online docs. The only time I ever print anything is for offline reading. I guess ymrdv. On Mon, Mar 16, 2009 at 9:15 PM, John Sgammato jsgamm...@imprivata.com wrote: * Put a logo (or message) on blank pages to show that they are not blank in error. Why on earth would you have blank PDF page? Who's going to take it, print it, and bind it, and then use only the printout? *** I very seldom read any serious documentation online. When I am on the computer, I am productive in other ways. If the PDF is not printer-friendly, I will think it was put together by a rookie. PDFs are suitable for printing, until you screw it up. ymmv john -- Bill Swallow Twitter: @techcommdood Blog: http://techcommdood.com LinkedIn: http://www.linkedin.com/in/techcommdood ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Off topic - three general documentation questions
Ian, In general, from a professional tech writer viewpoint, I think the first two ideas suck, but to go a little further, you didn't really provide enough info: * what is the goal of the redo? * what standard or style guide are you following that presents these suggestions, or which are you going to follow? * what audience do you write to * what kind of guides are you producing? Software / hardware, installation, administration, user, something else? As for the third idea, why have blank pages in a PDF at all? If it's so people can print a book traditional fashion... that may be the real question -- if that's useful, or required, or something else. In any case, I'd simply eliminate the blanks before I labeled them unless they are required AND a label is required by a standard. Cheers, Art Art Campbell art.campbell at gmail.com "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson No disclaimers apply. DoD 358 On Fri, Mar 13, 2009 at 5:45 AM, Saunders, Ian wrote: > Please forgive this off-topic query, but I have nowhere else to turn for help. > > My team are reviewing the Frame templates we use for producing PDF files. It > has been suggested that we: > > * ? ? ? ? Do not use chapter numbers/appendix letters > > * ? ? ? ? Begin main index entries with a capital letter > > * ? ? ? ? Put a logo (or message) on blank pages to show that they are not > blank in error. > > We have reached an impasse... > > I would be extremely grateful to anyone who can supply their take on the > relevant "industry standards" or maybe even point me at a definitive > statement. > > Many thanks! > > Ian Saunders > Syntellect Inc > > ___ > > > You are currently subscribed to Framers as art.campbell at gmail.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. >
Off topic - three general documentation questions
Saunders, Ian wrote: > My team are reviewing the Frame templates we use for producing PDF files. > It has been suggested that we: > > * Do not use chapter numbers/appendix letters > > * Begin main index entries with a capital letter > > * Put a logo (or message) on blank pages to show that they are not > blank in error. > > We have reached an impasse... > > I would be extremely grateful to anyone who can supply their take on the > relevant "industry standards" or maybe even point me at a definitive > statement. > I suggest assembling a collection of user manuals and books relevant to your industry as examples. I suspect you'll not find many embracing these ideas. Then alternatingly repeat "Why?" and "But nobody else does that!" until the proponents run screaming from the room. Richard Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 --
Off topic - three general documentation questions
Here are my thoughts based on my deliverables, my users' needs, and my employer's expectations. Your responses may vary significantly based on those and other variables. * Do not use chapter numbers/appendix letters I use chapter numbers in my printed books and PDFs, but not in online help. IMO they serve a valuable navigation function for the reader of a printed doc, helping to keep his/her bearings in the mass of pages. * Begin main index entries with a capital letter I would not, partly because an index entry is not a sentence and the capitalization might imply a meaning that does not exist, but also because it is much quicker to make an index entry by simply double-clicking the term without having to edit it on the spot. Of course, you still have to edit it if it starts a sentence or is capitalized for any other reason, but that is not so often. * Put a logo (or message) on blank pages to show that they are not blank in error. Because I print my books, I have all my chapters end on an even page, even if it is blank. My header and footer appear on those otherwise blank pages. The only time I get a question about it is when someone reads the PDF and comes upon a blank page for no obvious reason. Honestly, in 10 years with these templates the confusion has been brought to my attention maybe 6 times. Ymmv, etc, etc john -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Saunders, Ian Sent: Friday, March 13, 2009 5:45 AM To: framers at lists.frameusers.com Subject: Off topic - three general documentation questions Please forgive this off-topic query, but I have nowhere else to turn for help. My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. We have reached an impasse... I would be extremely grateful to anyone who can supply their take on the relevant "industry standards" or maybe even point me at a definitive statement. Many thanks! Ian Saunders Syntellect Inc ___ You are currently subscribed to Framers as jsgammato at imprivata.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/jsgammato%40imprivat a.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Off topic - three general documentation questions
> My team are reviewing the Frame templates we use for producing PDF files. > It has been suggested that we: > > * Do not use chapter numbers/appendix letters > > * Begin main index entries with a capital letter > > * Put a logo (or message) on blank pages to show that they are not > blank in error. Regarding index entries, _The Chicago Manual of Style_ states: "18.10 Initial lowercase letters in main headings. The first word of a main heading is normally capitalized only if capitalized in text-- a proper noun, a genus name, the title of a work, and so on. Indexes in the sciences often avoid initial capitals because the distinction between capitalized and lowercased terms in the text may be crucial. Traditionally, all main headings in an index were capitalized; Chicago recommends the practice only where the subentries are so numerous that capitalized main headings make for easier navigation." The CMOS is a great reference to have on hand. It always seems to have the answers. Mike Wickham
Off topic - three general documentation questions
> * ? ? ? ? Do not use chapter numbers/appendix letters Neither here nor there. Sometimes it's easier to reference by a single char, but ultimately this is a PDF and is searchable with a dynamic TOC. > * ? ? ? ? Begin main index entries with a capital letter Meh. Style issue. Let those who bark loudest win and then hold them to the convention. > * ? ? ? ? Put a logo (or message) on blank pages to show that they are not > blank in error. Why on earth would you have blank PDF page? Who's going to take it, print it, and bind it, and then use only the printout? -- Bill Swallow Twitter: @techcommdood Blog: http://techcommdood.com LinkedIn: http://www.linkedin.com/in/techcommdood
Off topic - three general documentation questions
> * Put a logo (or message) on blank pages to show that they are not > blank in error. Why on earth would you have blank PDF page? Who's going to take it, print it, and bind it, and then use only the printout? *** I very seldom read any serious documentation online. When I am on the computer, I am productive in other ways. If the PDF is not printer-friendly, I will think it was put together by a rookie. PDFs are suitable for printing, until you screw it up. ymmv john
Off topic - three general documentation questions
Interesting. When I'm on the computer, I'm all over the Help and online docs. The only time I ever print anything is for "offline" reading. I guess ymrdv. On Mon, Mar 16, 2009 at 9:15 PM, John Sgammato wrote: >> * ? ? ? ? Put a logo (or message) on blank pages to show that they are not >> blank in error. > > Why on earth would you have blank PDF page? Who's going to take it, > print it, and bind it, and then use only the printout? > > *** > I very seldom read any serious documentation online. When I am on the > computer, I am productive in other ways. If the PDF is not printer-friendly, > I will think it was put together by a rookie. PDFs are suitable for printing, > until you screw it up. > ymmv > john > -- Bill Swallow Twitter: @techcommdood Blog: http://techcommdood.com LinkedIn: http://www.linkedin.com/in/techcommdood
Off topic - three general documentation questions
Please forgive this off-topic query, but I have nowhere else to turn for help. My team are reviewing the Frame templates we use for producing PDF files. It has been suggested that we: * Do not use chapter numbers/appendix letters * Begin main index entries with a capital letter * Put a logo (or message) on blank pages to show that they are not blank in error. We have reached an impasse... I would be extremely grateful to anyone who can supply their take on the relevant "industry standards" or maybe even point me at a definitive statement. Many thanks! Ian Saunders Syntellect Inc
