RE: Remote Desktop and FrameMaker
I regularly use Frame remotely from various platforms with decent results. Application-wise it is pretty solid. Mostly, I use it over a local area network or across two centrally located LANs with one switch between them. How many 'hops' you have in between your desktop and remote machine, chapter size, how fast you scroll through your book, can play a big factor as well. I have used Frame 7 and 8 running on Windows and Frame 8 running on Solaris (remote machine) by way of Windows Remote Desktop and rdesktop (Linux) (local or 'desktop' machine) The only thing I have noticed is that the copy or ctrl+C command does not always buffer consistently between the remote and the desktop machine (Linux). I would use this for instance if I have some source material on the desktop I want to paste into my FrameMaker doc open on the remote machine. I've also noticed that hex key codes don't work when trying to type special characters using the number pad. Normal shortcuts that use the qwerty characters work seamlessly. This might work if you use Windows Remote Desktop from a Windows machine rather than the rdesktop Linux variant. If you have a good Network connection, which I do, that also helps things along. The Solaris machine I use is a bit dated, and I use it mainly for doc build and check in using FrameScript. But rdesktop-ing to it works as far as I have seen. HTH Reid From: framers-boun...@lists.frameusers.com on behalf of Catherine Woods Sent: Thu 9/10/2009 8:52 PM To: 'Brabson, Michelle'; framers@lists.frameusers.com Cc: 'Dressner, Elizabeth' Subject: RE: Remote Desktop and FrameMaker I was using FrameMaker with remote desktop today. It was fine as far as I could tell. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Brabson, Michelle Sent: Wednesday, August 26, 2009 8:28 AM To: framers@lists.frameusers.com Cc: Dressner, Elizabeth Subject: Remote Desktop and FrameMaker Hi-- Does anyone know if FrameMaker works with Remote Desktop? I have this set up and I find that several files I work with blow up. I do not have this problem on other configurations, that is, not using Remote Desktop. I am on FrameMaker 7.2. Any help is appreciated! Michelle __ Michelle Brabson * Technical Production Manager * SunGard Higher Education * 4 Country View Road, Malvern, PA 19355 * Tel 610-578-5040 * Fax 610-578-5400 * michelle.brab...@sungardhe.com * www.sungardhe.com Please consider the environment before printing this message. ___ You are currently subscribed to Framers as catw...@telus.net. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/catwood%40telus.net Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Remote Desktop and FrameMaker
I regularly use Frame remotely from various platforms with decent results. Application-wise it is pretty solid. Mostly, I use it over a local area network or across two centrally located LANs with one switch between them. How many 'hops' you have in between your desktop and remote machine, chapter size, how fast you scroll through your book, can play a big factor as well. I have used Frame 7 and 8 running on Windows and Frame 8 running on Solaris (remote machine) by way of Windows Remote Desktop and rdesktop (Linux) (local or 'desktop' machine) The only thing I have noticed is that the copy or ctrl+C command does not always buffer consistently between the remote and the desktop machine (Linux). I would use this for instance if I have some source material on the desktop I want to paste into my FrameMaker doc open on the remote machine. I've also noticed that hex key codes don't work when trying to type special characters using the number pad. Normal shortcuts that use the qwerty characters work seamlessly. This might work if you use Windows Remote Desktop from a Windows machine rather than the rdesktop Linux variant. If you have a good Network connection, which I do, that also helps things along. The Solaris machine I use is a bit dated, and I use it mainly for doc build and check in using FrameScript. But rdesktop-ing to it works as far as I have seen. HTH Reid From: framers-boun...@lists.frameusers.com on behalf of Catherine Woods Sent: Thu 9/10/2009 8:52 PM To: 'Brabson, Michelle'; framers at lists.frameusers.com Cc: 'Dressner, Elizabeth' Subject: RE: Remote Desktop and FrameMaker I was using FrameMaker with remote desktop today. It was fine as far as I could tell. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Brabson, Michelle Sent: Wednesday, August 26, 2009 8:28 AM To: framers at lists.frameusers.com Cc: Dressner, Elizabeth Subject: Remote Desktop and FrameMaker Hi-- Does anyone know if FrameMaker works with Remote Desktop? I have this set up and I find that several files I work with blow up. I do not have this problem on other configurations, that is, not using Remote Desktop. I am on FrameMaker 7.2. Any help is appreciated! Michelle __ Michelle Brabson * Technical Production Manager * SunGard Higher Education * 4 Country View Road, Malvern, PA 19355 * Tel 610-578-5040 * Fax 610-578-5400 * Michelle.Brabson at sungardhe.com * www.sungardhe.com Please consider the environment before printing this message. ___ You are currently subscribed to Framers as catwood at telus.net. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/catwood%40telus.net Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: [Free Framers] Search produces five identical listings
Hi Nancy, Sorry this is a week off. You have identified one of the common problems of not classic problems with searching --duplicates. Often times duplicates are a side effect to the automatic indexing process where the same source text already has hyperlinks from multiple places in the help project, website, or body of content you are feeding. So if the anchor tag looks like this: a href=ports.htmlreserved TCP port range/a ...and this complete anchor tag appears 2 or more times with the same anchor text (in blue for this explanation), and the end-user executes a keyword search on TCP port, port range, or something relevant, the example duplicate results you provided is analog to the results the user gets! Google and the rest do a 'link cardinality' trick where they check if the same achor text actually points to the same place on the same page so they can pick one of the results to be listed in the top ten or so hits you get back. It is not a tough thing to script this if somebody at your site is handy with python, java, or javascript, or whatever web application language is handy or makes sense. It is simple string comparison operations. The sequence is this: Query results come back and are fed to your dedup script -- Dedup script searches for links that are the same. If link is the same and anchor text is the same, delete the result record, repeat. -- de-duplicated query results are passed to the user. Just ensure that whoever writes the script gives you a switch to turn it on or off so you can check the query results in both cases to see if it is working to your satisfaction. Cheers, Reid From: Nancy Allison [mailto:nancy.allis...@verizon.net] Sent: Wed 7/29/2009 8:32 AM To: Reid Gray Subject: [Free Framers] Search produces five identical listings I've used Frame and Mif2Go to create a .chm file. When I use the Search tab to search for a term, I get five identical listings for some results, but not all. Example: Search for debounce produces Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Using the Favorites Tab Welcome to the Online Help The first five listings refer to a lengthy topic, which uses the word debounce seven times, if it matters. The second two are the H1 and subhead, in the same topic, which uses the word twice. What is causing the multiple listing, and is there anything I can do about it? --Nancy -- You are subscribed to the following list: Free Framers using the following email: rg...@interactivesupercomputing.com You may automatically unsubscribe from this list at any time by visiting the following URL: http://www.omsys.com/cgi-bin/dada/mail.cgi/u/framers/ You may also change your subscription by visiting this list's main screen: http://www.omsys.com/cgi-bin/dada/mail.cgi/list/framers If you're still having trouble, please contact the list owner at: mailto:owner-fram...@omsys.com Mailing List Powered by Dada Mail http://www.omsys.com/cgi-bin/dada/mail.cgi/what_is_dada_mail/= ___ 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.
[Free Framers] Search produces five identical listings
Hi Nancy, Sorry this is a week off. You have identified one of the common problems of not classic problems with searching --duplicates. Often times duplicates are a side effect to the automatic indexing process where the same source text already has hyperlinks from multiple places in the help project, website, or body of content you are feeding. So if the anchor tag looks like this: reserved TCP port range ...and this complete anchor tag appears 2 or more times with the same anchor text (in blue for this explanation), and the end-user executes a keyword search on "TCP port," "port range," or something relevant, the example duplicate results you provided is analog to the results the user gets! Google and the rest do a 'link cardinality' trick where they check if the same achor text actually points to the same place on the same page so they can pick one of the results to be listed in the top ten or so hits you get back. It is not a tough thing to script this if somebody at your site is handy with python, java, or javascript, or whatever web application language is handy or makes sense. It is simple string comparison operations. The sequence is this: Query results come back and are fed to your dedup script --> Dedup script searches for links that are the same. If link is the same and anchor text is the same, delete the result record, repeat. --> de-duplicated query results are passed to the user. Just ensure that whoever writes the script gives you a switch to turn it on or off so you can check the query results in both cases to see if it is working to your satisfaction. Cheers, Reid From: Nancy Allison [mailto:nancy.allis...@verizon.net] Sent: Wed 7/29/2009 8:32 AM To: Reid Gray Subject: [Free Framers] Search produces five identical listings I've used Frame and Mif2Go to create a .chm file. When I use the Search tab to search for a term, I get five identical listings for some results, but not all. Example: Search for "debounce" produces Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Resistor Debounce Values for First Touch Valuation Using the Favorites Tab Welcome to the Online Help The first five listings refer to a lengthy topic, which uses the word "debounce" seven times, if it matters. The second two are the H1 and subhead, in the same topic, which uses the word twice. What is causing the multiple listing, and is there anything I can do about it? --Nancy -- You are subscribed to the following list: Free Framers using the following email:rgray at interactivesupercomputing.com You may automatically unsubscribe from this list at any time by visiting the following URL: <http://www.omsys.com/cgi-bin/dada/mail.cgi/u/framers/> You may also change your subscription by visiting this list's main screen: <http://www.omsys.com/cgi-bin/dada/mail.cgi/list/framers> If you're still having trouble, please contact the list owner at: <mailto:owner-framers at omsys.com> Mailing List Powered by Dada Mail http://www.omsys.com/cgi-bin/dada/mail.cgi/what_is_dada_mail/=
[OT] API technical writer list?
Hi Framers, I was wondering if there were any lists around for API technical writers? LinkedIn groups? Thanks, Reid ___ 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.
[OT] API technical writer list?
Hi Framers, I was wondering if there were any lists around for API technical writers? LinkedIn groups? Thanks, Reid
RE: Standard font for technical documentation
For printed books the prevailing wisdom and studies show that serif font is easier to read. On the other hand, for display devices (electronic viewing) the prevailing studies and wisdom say that non-serif font is easier for humans to decode. Look at the books on your shelf. Check how many of these books have arial or helvetica font for the body text. The number should be few or zero. Now look at your copy machine user interface or your cell phone --these devices normally do use helvetica, arial, or verdana (san-serif font). Most tech docs tend to favor the printed media wisdom (serif font for body text) and use non serif for headings because they stand out. Aside from following the the prevailing wisdom, this combination has always looked good to me. There have been numerous studies in Human Computer Interaction (long before Google or Microsoft ever existed) they reveal that: - Non serif fonts are easier read on display devices - Using more than five typefaces (where color, weight, and italics all count as a new typeface) for a particular display increases human processing time. Art is right. This topic can create a fair amount of pointless and lively bike-shed-phenomenon-like discussion. So, be prepared for it. http://en.wikipedia.org/wiki/Wikipedia:Avoid_Parkinson's_Bicycle_Shed_Effect Reid From: framers-boun...@lists.frameusers.com on behalf of Art Campbell Sent: Mon 7/20/2009 8:22 AM To: mathieu jacquet Cc: framers@lists.frameusers.com Subject: Re: Standard font for technical documentation I think it depends on the application, how the documents are delivered, and what the company's stanard fonts (part of the corporate look, or branding, are). The other thing you should know is that for some reason, picking fonts amounts to a religious war with odd fervor among the participants. So you're unlikely to get one good answer. If I were you, I'd start with Adobe's Type Primer http://www.adobe.com/education/pdf/type_primer.pdf For material that will be printed or delivered via PDF and likely to be printed by the customer, I usually use a serif body font and serif heads. The one I'm working in now uses Palatino and Avant Garde. If the material will only be on-screen and/or web, I'd go with serif fonts for both body and heads, and I'd pick one that was designed for on-screen display -- very few are, or were. Verdana is one of them. Arial is not Most type foundries today will have a few. If you want more detail, on why, Google font readability research 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 Mon, Jul 20, 2009 at 2:57 AM, mathieu jacquetbobi...@hotmail.com wrote: Dear all, is there any standard font for writing Getting Started guides, User Manuals and other technical documents? Which one do you personnally use? Do you find that some fonts offer a better reading quality than others? Thank you very much in anticipation. Yours sincerely, Mathieu. _ Téléphonez gratuitement à tous vos proches avec Windows Live Messenger ! Téléchargez-le maintenant ! http://www.windowslive.fr/messenger/1.asp ___ 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 rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Standard font for technical documentation
For printed books the prevailing wisdom and studies show that serif font is easier to read. On the other hand, for display devices (electronic viewing) the prevailing studies and wisdom say that non-serif font is easier for humans to decode. Look at the books on your shelf. Check how many of these books have arial or helvetica font for the body text. The number should be few or zero. Now look at your copy machine user interface or your cell phone --these devices normally do use helvetica, arial, or verdana (san-serif font). Most tech docs tend to favor the printed media wisdom (serif font for body text) and use non serif for headings because they stand out. Aside from following the the prevailing wisdom, this combination has always looked good to me. There have been numerous studies in Human Computer Interaction (long before Google or Microsoft ever existed) they reveal that: - Non serif fonts are easier read on display devices - Using more than five typefaces (where color, weight, and italics all count as a new typeface) for a particular display increases human processing time. Art is right. This topic can create a fair amount of pointless and lively "bike-shed-phenomenon-like" discussion. So, be prepared for it. http://en.wikipedia.org/wiki/Wikipedia:Avoid_Parkinson's_Bicycle_Shed_Effect Reid From: framers-boun...@lists.frameusers.com on behalf of Art Campbell Sent: Mon 7/20/2009 8:22 AM To: mathieu jacquet Cc: framers at lists.frameusers.com Subject: Re: Standard font for technical documentation I think it depends on the application, how the documents are delivered, and what the company's stanard fonts (part of the corporate "look," or branding, are). The other thing you should know is that for some reason, picking fonts amounts to a religious war with odd fervor among the participants. So you're unlikely to get one good answer. If I were you, I'd start with Adobe's Type Primer http://www.adobe.com/education/pdf/type_primer.pdf For material that will be printed or delivered via PDF and likely to be printed by the customer, I usually use a serif body font and serif heads. The one I'm working in now uses Palatino and Avant Garde. If the material will only be on-screen and/or web, I'd go with serif fonts for both body and heads, and I'd pick one that was designed for on-screen display -- very few are, or were. Verdana is one of them. Arial is not Most type foundries today will have a few. If you want more detail, on why, Google "font readability research" 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 Mon, Jul 20, 2009 at 2:57 AM, mathieu jacquet wrote: > > Dear all, > is there any "standard font" for writing Getting Started guides, User Manuals > and other technical documents? Which one do you personnally use? Do you find > that some fonts offer a better "reading quality" than others? > Thank you very much in anticipation. > Yours sincerely, > Mathieu. > > > _ > T?l?phonez gratuitement ? tous vos proches avec Windows Live Messenger ! > T?l?chargez-le maintenant ! > http://www.windowslive.fr/messenger/1.asp > ___ > > > 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. > ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Heading levels in a UG
Hi Framers, In general if your heading levels descend below three or four in user documentation, you need to take a step back, analyze, and rebalance. Nothing new here, just the old axiom be nice to your user... You can apply the same principle to the navigation over enterprise websites. If you find yourself descending past three or four, redefine your level 1 heads (perhaps a level 1 head gets removed and two level 2s beneath it promoted). Do what makes sense. Rebalance it. If you find yourself descending past four, five, or six you might have a guide hiding within a guide. Break it out. An outline or book structure is like a decision tree or even a binary tree. The more levels you force me to descend, the higher my cost in 'look-up' latency, the harder it is for me to recall the context or navigate back to the heading, and the more painfully disoriented I become. If disorientation is a feature or adding levels is a requirement for your particular documentation (legal writing, city electrical codes, cell phone billing statements, philisophical treatise), then you are okay in descending as many levels as needed, just remember to index or enumerate 'said' headings adequately so folks can cite them at a later time from equally disorienting prose. Another version of be nice to your user is don't Hegel your audience (although even Hegel had a tendency to articulate or 'piece' general concepts into threes). Cheers, Reid From: framers-boun...@lists.frameusers.com on behalf of syed.hos...@aeris.net Sent: Wed 7/15/2009 11:03 AM To: Evanth, Henrik; framers@lists.frameusers.com Subject: RE: Heading levels in a UG I use a maximum of 4 ... anything more, and the heading numbering scheme gets quite clumsy and distracts from the content. Z -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Evanth, Henrik Sent: Wednesday, July 15, 2009 12:25 AM To: framers@lists.frameusers.com Subject: OT: Heading levels in a UG Hi All I have an off-topic question that may or may not interest you. We are having a discussion at the office regarding the maximum levels of heading that a User guide/User manual can/should contain. Do you know of any best practice rules that define how deep a publication should/could be. Personally I think that 6 levels is too deep for a user, but that is just a personal preference that I cannot back up with evidence. Heading 1 Heading 2 Heading 3 Heading 4 Heading 5 Heading 6 Insights, comments or instructions are highly appreciated. Best Regards /Henrik ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Heading levels in a UG
Hi Framers, In general if your heading levels descend below three or four in user documentation, you need to take a step back, analyze, and rebalance. Nothing new here, just the old axiom "be nice to your user..." You can apply the same principle to the navigation over enterprise websites. If you find yourself descending past three or four, redefine your level 1 heads (perhaps a level 1 head gets removed and two level 2s beneath it promoted). Do what makes sense. Rebalance it. If you find yourself descending past four, five, or six you might have a guide hiding within a guide. Break it out. An outline or book structure is like a decision tree or even a binary tree. The more levels you force me to descend, the higher my cost in 'look-up' latency, the harder it is for me to recall the context or navigate back to the heading, and the more painfully disoriented I become. If disorientation is a feature or adding levels is a requirement for your particular documentation (legal writing, city electrical codes, cell phone billing statements, philisophical treatise), then you are okay in descending as many levels as needed, just remember to index or enumerate 'said' headings adequately so folks can cite them at a later time from equally disorienting prose. Another version of "be nice to your user" is "don't Hegel your audience" (although even Hegel had a tendency to articulate or 'piece' general concepts into threes). Cheers, Reid From: framers-bounces at lists.frameusers.com on behalf of syed.hos...@aeris.net Sent: Wed 7/15/2009 11:03 AM To: Evanth, Henrik; framers at lists.frameusers.com Subject: RE: Heading levels in a UG I use a maximum of 4 ... anything more, and the heading numbering scheme gets quite clumsy and distracts from the content. Z -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Evanth, Henrik Sent: Wednesday, July 15, 2009 12:25 AM To: framers at lists.frameusers.com Subject: OT: Heading levels in a UG Hi All I have an off-topic question that may or may not interest you. We are having a discussion at the office regarding the maximum levels of heading that a User guide/User manual can/should contain. Do you know of any best practice rules that define how deep a publication should/could be. Personally I think that 6 levels is too deep for a user, but that is just a personal preference that I cannot back up with "evidence". Heading 1 Heading 2 Heading 3 Heading 4 Heading 5 Heading 6 Insights, comments or instructions are highly appreciated. Best Regards /Henrik ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
For status messages such as the one you cite below, I think using please is perfectly okay. I also agree with omitting words that add nothing to the meaning of the sentence; however, the use of please can convey a specific and useful tone. It's not inappropriate for a status or feedback alert message. That said, if in a distinct case we are directing the user to perform a specific action (procedural documentation), it's true we don't want the tone to sound as if we are begging. Example: Please back up your configuration file before you edit it. (Too soft, sounds optional) Back up your configuration file before you edit it. [Period.] Rules are good, but who hasn't said first you learn the rules...and then you learn to break them [in exceptional cases]? --E.B. White himself might have uttered this once or twice. -Original Message- From: framers-boun...@lists.frameusers.com on behalf of Andersen, Verner Engell VEA Sent: Fri 6/26/2009 4:30 AM To: framers@lists.frameusers.com Subject: OT: Use of please in technical documentation and messages on screen Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner Radiometer Medical ApS Akandevej 21 2700 Bronshoj Denmark Phone: +45 38 27 38 27 CVR: 27 50 91 85 Please be advised that this email may contain confidential information. If you are not the intended recipient, please do not read, copy or re-transmit this email. If you have received this email in error, please notify us by email by replying to the sender and by telephone (call us collect at +1 202-828-0850) and delete this message and any attachments. Thank you in advance for your cooperation and assistance. In addition, Danaher and its subsidiaries disclaim that the content of this email constitutes an offer to enter into, or the acceptance of, any contract or agreement or any amendment thereto; provided that the foregoing disclaimer does not invalidate the binding effect of any digital or other electronic reproduction of a manual signature that is included in any attachment to this email. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Use of "please" in technical documentation and messages on screen
For status messages such as the one you cite below, I think using "please" is perfectly okay. I also agree with omitting words that add nothing to the meaning of the sentence; however, the use of "please" can convey a specific and useful tone. It's not inappropriate for a status or feedback alert message. That said, if in a distinct case we are directing the user to perform a specific action (procedural documentation), it's true we don't want the tone to sound as if we are begging. Example: "Please back up your configuration file before you edit it." (Too soft, sounds optional) "Back up your configuration file before you edit it." [Period.] Rules are good, but who hasn't said "first you learn the rules...and then you learn to break them [in exceptional cases]"? --E.B. White himself might have uttered this once or twice. -Original Message- From: framers-boun...@lists.frameusers.com on behalf of Andersen, Verner Engell VEA Sent: Fri 6/26/2009 4:30 AM To: framers at lists.frameusers.com Subject: OT: Use of "please" in technical documentation and messages on screen Hi Once I learned that you shouln't use the word "please" in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? "We are updating the result list, please wait" Best regards, Verner Radiometer Medical ApS Akandevej 21 2700 Bronshoj Denmark Phone: +45 38 27 38 27 CVR: 27 50 91 85 Please be advised that this email may contain confidential information. If you are not the intended recipient, please do not read, copy or re-transmit this email. If you have received this email in error, please notify us by email by replying to the sender and by telephone (call us collect at +1 202-828-0850) and delete this message and any attachments. Thank you in advance for your cooperation and assistance. In addition, Danaher and its subsidiaries disclaim that the content of this email constitutes an offer to enter into, or the acceptance of, any contract or agreement or any amendment thereto; provided that the foregoing disclaimer does not invalidate the binding effect of any digital or other electronic reproduction of a manual signature that is included in any attachment to this email. ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Developer documentation
This builds on the comments by Chris. You definitely need: -- - Pre-requisites for the software - Unpacking the software - Architecture diagram. (Typically in an overview section) The architecture diagram identifies where the custom application these developers will code fits in the scheme of the application framework, the platform, and the network. What libraries must it include? What platforms are these libraries available on? What methods or protocols are used to pass data? - Working examples. Programming or developer documentation is best when it contains working examples. You can can these from systems engineers, sales engineers, or developers. Most examples have a step where you create or construct an object and use its methods or add or get data from that object. This would be your hello world example. Nice to have: -- - Class diagrams. If your stuff inherits methods from base classes, it is nice to show this. There are also 3rd party tools that can generate these diagrams right from the code. Examples of complete custom apps (in an appendix for instance). Things to be aware of: -- Chances are that your programming interfaces follow or demonstrate qualities of a particular design pattern. Find out what design pattern the interfaces follow before you begin to write. You can familiarize yourself with the design pattern's basic concepts and philosophy very quickly by looking it up on Wikipedia and discussing with your favorite developer. This information provides your frame of reference as you write. Find out and establish early on what should be visible to the end-user or developer and what is opaque. Otherwise, you could spend a lot of time writing about interfaces used in house but not for customers except maybe where the customer is a partner. All in all your project sounds cool. Have fun! Reid From: framers-boun...@lists.frameusers.com on behalf of Chris Despopoulos Sent: Thu 6/25/2009 8:16 AM To: framers@lists.frameusers.com Subject: Re: Developer documentation I'll take a crack at this... You should try to find developer docs that you can emulate. To start, you need to figure out some particulars of the dev platform -- what language (C/C++, Java, Flash, etc.), what is the dev environment (is there a specific IDE (integrated development environment) you support?), is this an API into a proprietary game engine, or a framework for integrating external technologies like Flash into a TV platform? Understanding and being able to articulate these issues will help you find examples of docs that approximate your goal. Don't stick to Dev docs for TV Games -- cast a wider net. You can look at any dev good docs and hope to see the following: * Overview/description/use cases -- Why even bother with this dev environment * Architecture -- How is the platform organized, what talks to what, and what components do you program * Dev tools -- Languages and IDEs supported * Installation and use -- How to link your technology into a program * Hello World -- The smallest possible program. This is important because the customer can use it to prove the installation is good * Sample recipes -- Nice to have... listings of code that performs specific tasks * Reference -- Each method, function, or whatever types of calls you expose with the signature (what you pass in and what it returns), synopsis, required libs or packages, discussion (only use this method if the moon is full), and maybe sample code There's stuff to look at. Look at the MSDN - Microsoft Developer's Network. So... is this advice, experience, or sympathy? Whatever it is, I hope it's useful... cud ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Developer documentation
This builds on the comments by Chris. You definitely need: -- - Pre-requisites for the software - Unpacking the software - Architecture diagram. (Typically in an overview section) The architecture diagram identifies where the custom application these developers will code fits in the scheme of the application framework, the platform, and the network. What libraries must it include? What platforms are these libraries available on? What methods or protocols are used to pass data? - Working examples. Programming or developer documentation is best when it contains working examples. You can can these from systems engineers, sales engineers, or developers. Most examples have a step where you create or construct an object and use its methods or add or get data from that object. This would be your "hello world" example. Nice to have: -- - Class diagrams. If your stuff inherits methods from base classes, it is nice to show this. There are also 3rd party tools that can generate these diagrams right from the code. Examples of complete custom apps (in an appendix for instance). Things to be aware of: -- Chances are that your programming interfaces follow or demonstrate qualities of a particular design pattern. Find out what design pattern the interfaces follow before you begin to write. You can familiarize yourself with the design pattern's basic concepts and philosophy very quickly by looking it up on Wikipedia and discussing with your favorite developer. This information provides your frame of reference as you write. Find out and establish early on what should be visible to the end-user or developer and what is opaque. Otherwise, you could spend a lot of time writing about interfaces used in house but not for customers except maybe where the customer is a partner. All in all your project sounds cool. Have fun! Reid From: framers-boun...@lists.frameusers.com on behalf of Chris Despopoulos Sent: Thu 6/25/2009 8:16 AM To: framers at lists.frameusers.com Subject: Re: Developer documentation I'll take a crack at this... You should try to find developer docs that you can emulate. To start, you need to figure out some particulars of the dev platform -- what language (C/C++, Java, Flash, etc.), what is the dev environment (is there a specific IDE (integrated development environment) you support?), is this an API into a proprietary game engine, or a framework for integrating external technologies like Flash into a TV platform? Understanding and being able to articulate these issues will help you find examples of docs that approximate your goal. Don't stick to "Dev docs for TV Games" -- cast a wider net. You can look at any dev good docs and hope to see the following: * Overview/description/use cases -- Why even bother with this dev environment * Architecture -- How is the platform organized, what talks to what, and what components do you program * Dev tools -- Languages and IDEs supported * Installation and use -- How to link your technology into a program * Hello World -- The smallest possible program. This is important because the customer can use it to prove the installation is good * Sample "recipes" -- Nice to have... listings of code that performs specific tasks * Reference -- Each method, function, or whatever types of calls you expose with the signature (what you pass in and what it returns), synopsis, required libs or packages, discussion (only use this method if the moon is full), and maybe sample code There's stuff to look at. Look at the MSDN - Microsoft Developer's Network. So... is this advice, experience, or sympathy? Whatever it is, I hope it's useful... cud ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
Thanks Andy, I agree. If words stick to your gray matter, echo in your head like music, and if you can't help yourself from teasing them apart at their roots and stems you are probably in the right profession. To be a writer you need to love words. Also note endianness came originally from literature (Gulliver's Travels). Agreed. Writers use words to suit the lexicon of their audience. If you are writing for USA Today, it's best not to use the vocabulary of the Harvard Business Review. If you are writing a release note or a README, you wouldn't want the tone and vocabulary to be more in line with a low-level language programmer's guide. BTW: Great thread. Reid From: framers-boun...@lists.frameusers.com on behalf of Andy Kass Sent: Fri 5/22/2009 4:25 PM To: framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! I've enjoyed reading all the input on this thread, and I had a few more thoughts. Unfortunately, the way Reid writes it below, it looks like anyone can have the writer role. I would've written: 4. Technical Writer who knows enough to understand the SME, learns about the audience and its lingo, distills all the essentials out of these to make an easy to absorb document, and knows the tools and formats well enough to do it all quickly. In any job, I think people need their core skills but also an understanding and certain competency in the skills of those around them. To that extent, I'm sure engineers can and do write decent docs sometimes, but they're probably more efficient at their engineering tasks. I'm pretty sure we all know this, but it is exactly this that is important to communicate in the case of this pointy-haired boss. Nor does the boss seem to understand how a good writer can save money and improve customer satisfaction. To be a good writer, you also have to understand where management is coming from... BTW, I actually don't think it's productive for writers to use big words for the sake of using big words. Writers must use whatever words speak to their audience. Andy ak...@jaspersoft.com Date: Wed, 20 May 2009 14:51:39 -0400 From: Reid Gray rg...@interactivesupercomputing.com Subject: RE: Procedure How to Write a Manual! I think the list agrees that not just anybody can write a good manual. And No, writers cannot be just anybody. They must be committed, they need to love language, and as Annie Dillard says ...you really need to like words... words such as 'transmogrify' Or, if you will extend the metaphor to IT, endianess. The best writing happens as a collective effort with the writer at the center. So, for example, take manuals. To write a good manual, one needs: 1. Subject matter experts for authoritative content 2. Enthusiastic reviewers who know the audience and have exposure to the subject matter 3. Editors who know the language 4. The technical writer Trying as a single individual to serve in roles 1 through 4 is possible, but the more 'eyes' you have scanning the pages the better the expected outcome. This is especially true if you are writing complete books, manuals, and periodicals, from scratch. There is also an equally beneficial flip side to this postulate. If you find either transmogrify or endianess to be ugly, and if you think anybody in particular can plant a garden, repair an automobile, or write a technical manual, you might be management material. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Procedure How to Write a Manual!
Thanks Andy, I agree.
If words stick to your gray matter, echo in your head like music, and if you
can't help yourself from teasing them apart at their roots and stems you are
probably in the right profession. To be a writer you need to love words.
Also note "endianness" came originally from literature ("Gulliver's Travels).
Agreed. Writers use words to suit the lexicon of their audience. If you are
writing for USA Today, it's best not to use the vocabulary of the Harvard
Business Review. If you are writing a release note or a README, you wouldn't
want the tone and vocabulary to be more in line with a low-level language
programmer's guide.
BTW: Great thread.
Reid
From: framers-boun...@lists.frameusers.com on behalf of Andy Kass
Sent: Fri 5/22/2009 4:25 PM
To: framers at lists.frameusers.com
Subject: RE: Procedure How to Write a Manual!
I've enjoyed reading all the input on this thread, and I had a few more
thoughts.
Unfortunately, the way Reid writes it below, it looks like anyone can have the
writer role. I would've written:
4. Technical Writer who knows enough to understand the SME, learns about the
audience and its lingo, distills all the essentials out of these to make an
easy to absorb document, and knows the tools and formats well enough to do it
all quickly.
In any job, I think people need their core skills but also an understanding and
certain competency in the skills of those around them. To that extent, I'm sure
engineers can and do write decent docs sometimes, but they're probably more
efficient at their engineering tasks.
I'm pretty sure we all know this, but it is exactly this that is important to
communicate in the case of this pointy-haired boss. Nor does the boss seem to
understand how a good writer can save money and improve customer satisfaction.
To be a good writer, you also have to understand where management is coming
from...
BTW, I actually don't think it's productive for writers to use big words for
the sake of using big words. Writers must use whatever words speak to their
audience.
Andy
akass at jaspersoft.com
> Date: Wed, 20 May 2009 14:51:39 -0400
> From: "Reid Gray"
> Subject: RE: Procedure How to Write a Manual!
>
> I think the list agrees that not just anybody can write a
> good manual. And "No," writers cannot be just "anybody."
> They must be committed, they need to love language, and
> as Annie Dillard says "...you really need to like words...
> words such as 'transmogrify'"
>
> Or, if you will extend the metaphor to IT, "endianess."
>
> The best writing happens as a collective effort with the
> writer at the center. So, for example, take manuals. To
> write a good manual, one needs:
> 1. Subject matter experts for authoritative content
> 2. Enthusiastic reviewers who know the audience and have
> exposure to the subject matter
> 3. Editors who know the language
> 4. The technical writer
>
> Trying as a single individual to serve in roles 1 through
> 4 is possible, but the more 'eyes' you have scanning the
> pages the better the expected outcome. This is especially
> true if you are writing complete books, manuals, and
> periodicals, from scratch.
>
> There is also an equally beneficial flip side to this postulate.
> If you find either "transmogrify" or "endianess" to be ugly,
> and if you think anybody in particular can plant a garden,
> repair an automobile, or write a technical manual, you might
> be management material.
___
You are currently subscribed to Framers as rgray at
interactivesupercomputing.com.
Send list messages to framers at lists.frameusers.com.
To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com
Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
RE: Procedure How to Write a Manual!
I think the list agrees that not just anybody can write a good manual. And No, writers cannot be just anybody. They must be committed, they need to love language, and as Annie Dillard says ...you really need to like words...words such as 'transmogrify' Or, if you will extend the metaphor to IT, endianess. The best writing happens as a collective effort with the writer at the center. So, for example, take manuals. To write a good manual, one needs: 1. Subject matter experts for authoritative content 2. Enthusiastic reviewers who know the audience and have exposure to the subject matter 3. Editors who know the language 4. The technical writer Trying as a single individual to serve in roles 1 through 4 is possible, but the more 'eyes' you have scanning the pages the better the expected outcome. This is especially true if you are writing complete books, manuals, and periodicals, from scratch. There is also an equally beneficial flip side to this postulate. If you find either transmogrify or endianess to be ugly, and if you think anybody in particular can plant a garden, repair an automobile, or write a technical manual, you might be management material. From: framers-boun...@lists.frameusers.com on behalf of Richard Melanson Sent: Tue 5/19/2009 9:21 AM To: Robert Shelton; Avraham Makeler; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Robert Shelton Sent: Monday, May 18, 2009 2:32 PM To: Avraham Makeler; framers@lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Sharon Burton This is easy. 14 steps: 1. Identify the audience 2. Identify the information needs of that audience (job aids, user guides, and so on) 3. Identify the tasks the audience needs to do 4. Identify the supporting info the audience needs to do those tasks 5. Identify the best way to deliver the information (PDF, help, others) 6. Create a plan that layout all this information 7. Assign time estimates to the plan 8. Decide what can be cut due to time limitations 9. Start creating the information, adapting to the changing product 10. Review by others 11. Make the review changes 12. Build gold candidates 13. Deliver the finals 14. Archive the finals, including all planning information Of course, these steps include a lot of embedded steps and domain knowledge in our field. But these are the steps. I think you skipped something important: 1. Hire a tech writer. Bob Let what comes, come, Let what goes, go, Find out what remains. Sri Ramana Maharshi ___ You are currently subscribed to Framers as rmelan...@spirecorp.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor p.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Procedure How to Write a Manual!
I think the list agrees that not just anybody can write a good manual. And "No," writers cannot be just "anybody." They must be committed, they need to love language, and as Annie Dillard says "...you really need to like words...words such as 'transmogrify'" Or, if you will extend the metaphor to IT, "endianess." The best writing happens as a collective effort with the writer at the center. So, for example, take manuals. To write a good manual, one needs: 1. Subject matter experts for authoritative content 2. Enthusiastic reviewers who know the audience and have exposure to the subject matter 3. Editors who know the language 4. The technical writer Trying as a single individual to serve in roles 1 through 4 is possible, but the more 'eyes' you have scanning the pages the better the expected outcome. This is especially true if you are writing complete books, manuals, and periodicals, from scratch. There is also an equally beneficial flip side to this postulate. If you find either "transmogrify" or "endianess" to be ugly, and if you think anybody in particular can plant a garden, repair an automobile, or write a technical manual, you might be management material. From: framers-boun...@lists.frameusers.com on behalf of Richard Melanson Sent: Tue 5/19/2009 9:21 AM To: Robert Shelton; Avraham Makeler; framers at lists.frameusers.com Subject: RE: Procedure How to Write a Manual! -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Robert Shelton Sent: Monday, May 18, 2009 2:32 PM To: Avraham Makeler; framers at lists.frameusers.com Subject: RE: Procedure How to Write a Manual! > -Original Message- > From: framers-bounces at lists.frameusers.com > [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon > Burton > > This is easy. 14 steps: > > 1. Identify the audience > 2. Identify the information needs of that audience (job aids, user > guides, and so on) 3. Identify the tasks the audience needs to do 4. > Identify the supporting info the audience needs to do those tasks 5. > Identify the best way to deliver the information (PDF, help, others) > 6. Create a plan that layout all this information 7. Assign time > estimates to the plan 8. Decide what can be cut due to time > limitations 9. > Start creating the information, adapting to the changing product 10. > Review by others 11. Make the review changes 12. > Build "gold" candidates 13. Deliver the finals 14. Archive the finals, > including all planning information > > Of course, these steps include a lot of embedded steps and domain > knowledge in our field. But these are the steps. I think you skipped something important: 1. Hire a tech writer. Bob "Let what comes, come, Let what goes, go, Find out what remains." Sri Ramana Maharshi ___ You are currently subscribed to Framers as rmelanson at spirecorp.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor p.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Today's exercise in misunderstanding English
Chicago, eh? Be put in a cauldron of lead and usurer's grease, amongst a whole million of cutpurses, and there boil like a gammon of bacon that will never be enough. The Earl of Oxford was a Celtics fan. Your turn. http://www.pangloss.com/seidel/Shaker/index.html :-b Reid From: framers-boun...@lists.frameusers.com on behalf of Martinek, Carla Sent: Fri 4/24/2009 11:31 AM To: framers@lists.frameusers.com Subject: RE: Today's exercise in misunderstanding English Forsooth, and if thy language dost ne'er evolv'd, henceforth thee wouldst speaketh as the ancient Bard. Verily, the words of man must changeth and groweth as the seasons change -- looketh upon all the wordings which the Bard hast introduc'd into our speech. Woulds't thou changeth all that? -Carla (with apologies, but since yesterday was Talk Like Shakespeare Day in Chicago...) -Original Message- From: techwr-l-bounces+cmartinek=zebra@lists.techwr-l.com [mailto:techwr-l-bounces+cmartinek=zebra@lists.techwr-l.com] On Behalf Of Handy, David Sent: Friday, April 24, 2009 7:02 AM To: Gene Kim-Eng; techw...@lists.techwr-l.com Subject: RE: Today's exercise in misunderstanding English Buck it, Gene - buck it! This isn't just a matter of a new word gatecrashing the dictionary. This is key grammar. The number of people who think that legalized bad grammar is a portent of a crumbling civilization is kinda small, but it includes me; and if we writers don't jump up and down about this, nobody will. Grammar = expressivity. Replace sensible grammar rules with ok, whatever and you limit people's ability to say *exactly* what they mean. By the way, I'm not jumping on Gene here, or whoever wrote the original sentence - gramnmar is tough, time is short, and jargon happens. But remember Gandhi - be the lexical change you want to see in the world! - CONFIDENTIAL- This email and any files transmitted with it are confidential, and may also be legally privileged. If you are not the intended recipient, you may not review, use, copy, or distribute this message. If you receive this email in error, please notify the sender immediately by reply email and then delete this email. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Today's exercise in misunderstanding English
Chicago, eh? "Be put in a cauldron of lead and usurer's grease, amongst a whole million of cutpurses, and there boil like a gammon of bacon that will never be enough." The Earl of Oxford was a Celtics fan. Your turn. http://www.pangloss.com/seidel/Shaker/index.html :-b Reid From: framers-boun...@lists.frameusers.com on behalf of Martinek, Carla Sent: Fri 4/24/2009 11:31 AM To: framers at lists.frameusers.com Subject: RE: Today's exercise in misunderstanding English Forsooth, and if thy language dost ne'er evolv'd, henceforth thee wouldst speaketh as the ancient Bard. Verily, the words of man must changeth and groweth as the seasons change -- looketh upon all the wordings which the Bard hast introduc'd into our speech. Woulds't thou changeth all that? -Carla (with apologies, but since yesterday was "Talk Like Shakespeare Day" in Chicago...) -Original Message- From: techwr-l-bounces+cmartinek=zebra@lists.techwr-l.com [mailto:techwr-l-bounces+cmartinek=zebra.com at lists.techwr-l.com] On Behalf Of Handy, David Sent: Friday, April 24, 2009 7:02 AM To: Gene Kim-Eng; techwr-l at lists.techwr-l.com Subject: RE: Today's exercise in misunderstanding English Buck it, Gene - buck it! This isn't just a matter of a new word gatecrashing the dictionary. This is key grammar. The number of people who think that legalized bad grammar is a portent of a crumbling civilization is kinda small, but it includes me; and if we writers don't jump up and down about this, nobody will. Grammar = expressivity. Replace sensible grammar rules with "ok, whatever" and you limit people's ability to say *exactly* what they mean. By the way, I'm not jumping on Gene here, or whoever wrote the original sentence - gramnmar is tough, time is short, and jargon happens. But remember Gandhi - be the lexical change you want to see in the world! - CONFIDENTIAL- This email and any files transmitted with it are confidential, and may also be legally privileged. If you are not the intended recipient, you may not review, use, copy, or distribute this message. If you receive this email in error, please notify the sender immediately by reply email and then delete this email. ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Technical Writing Certificate
Kelly's post was a real motivator. Terrific information. I hope somebody is tabulating it! How about professional writing programs? That might be useful information as well. Reid From: framers-boun...@lists.frameusers.com on behalf of Karen L. Zorn Sent: Wed 4/8/2009 3:51 PM To: framers@lists.frameusers.com Cc: barry.m...@asu.edu Subject: Re: Technical Writing Certificate University of Arizona, Polytechnic has a very robust undergrad Technical Writing degree program. Most/all of the courses are online. They are in the process of launching a graduate program. For more information, you can contact Dr. Barry Maid (barry.m...@asu.edu). Karen L. Zorn ZornTech LLC Kelly McDaniel wrote: snip IMHO, the better approach is a technical writing degree, even an associate's degree has more value than a testing certificate. The problem with a tech writing degree is finding an accredited educational institution with a well-developed curriculum. I have been associated with the tech trade over 30 years and I cannot think of any...Kelly. seawi...@aol.com wrote: Hello Framers: Would someone please recommend a couple of online certificate programs that I can take to become a technical writer? What is the best online writing course available?? Thanks from a Newbie! ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Technical Writing Certificate
Kelly's post was a real motivator. Terrific information. I hope somebody is tabulating it! How about professional writing programs? That might be useful information as well. Reid From: framers-boun...@lists.frameusers.com on behalf of Karen L. Zorn Sent: Wed 4/8/2009 3:51 PM To: framers at lists.frameusers.com Cc: Barry.Maid at asu.edu Subject: Re: Technical Writing Certificate University of Arizona, Polytechnic has a very robust undergrad Technical Writing degree program. Most/all of the courses are online. They are in the process of launching a graduate program. For more information, you can contact Dr. Barry Maid (Barry.Maid at asu.edu). Karen L. Zorn ZornTech LLC Kelly McDaniel wrote: > > IMHO, the better approach is a technical writing degree, even an > associate's degree has more value than a testing certificate. The > problem with a tech writing degree is finding an accredited educational > institution with a well-developed curriculum. I have been associated > with the tech trade over 30 years and I cannot think of any...Kelly. > > seawin22 at aol.com wrote: > > Hello Framers: > > Would someone please recommend a couple of online certificate programs > that I can take to become a technical writer? > > What is the best online writing course available?? > > Thanks from a Newbie! > > ___ You are currently subscribed to Framers as rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: PDF create with FMbatch fails --doh!
Yikes, it is possible. You are correct, Sir! Looks like i have some Solaris admin to do. Many thanks for your expert and perennial contributions to this list. :-) Reid From: framers-boun...@lists.frameusers.com on behalf of Shlomo Perets Sent: Tue 3/31/2009 10:46 AM To: Reid Gray; framers@lists.frameusers.com Subject: Re: PDF create with FMbatch fails --doh! Reid, You wrote: We build our books here with FMbatch on a --you guessed it-- Solaris machine. We check them out of source control and build them automagically, but as you can see from the noise below a book I just created from scratch on my Windows machine is not playing nice with FMbatch. Earlier I had an error on pg 18. I saved the book as MIF (exported really). Then opened the MIF and saved as Frame 8 to dispell the demons as it were. So, it looks like the bad behavior has moved to p 3, which is kind of a good thing. --I guess Adobe must build its books in reverse. Anyhow, if you have any ideas what might be plaguing me here please give a shout. I'm going home. Reid CID support library initialization completed. %%[ Warning: Empty job. No PDF file produced. ] %% Normalizer 8.0. UsePrologue is false. %%[ Warning: Empty job. No PDF file produced. ] %% Done %%[ Error: undefined; OffendingCommand: pdfmark; ErrorInfo: Rect ]%% Stack: /ANN /Link /Subtype /G3.998318 /D /GoToR ... Is it possible that you are using the initial release of FM8.0? The initial FM8.0 release handled link information incorrectly (missing two angle brackets in the definition of the link's action in the PS file). Check whether you can update FM8 (applying available patches). If not, as a workaround: turn Tagged PDF on (without selecting specific tags) in FM's PDF Setup dialog box [note: I don't generally recommend producing Tagged PDFs from FrameMaker] Shlomo Perets MicroType, http://www.microtype.com http://www.microtype.com/ FrameMaker/Acrobat training consulting * FM-to-Acrobat TimeSavers/Assistants Template Design, Single Sourcing, FM-to-PDF Acrobat courses ___ You are currently subscribed to Framers as flor...@westinghouse.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/florama%40westinghouse.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.
PDF create with FMbatch fails --doh!
Yikes, it is possible. You are correct, Sir! Looks like i have some Solaris admin to do. Many thanks for your expert and perennial contributions to this list. :-) Reid From: framers-boun...@lists.frameusers.com on behalf of Shlomo Perets Sent: Tue 3/31/2009 10:46 AM To: Reid Gray; framers at lists.frameusers.com Subject: Re: PDF create with FMbatch fails --doh! Reid, You wrote: >We build our books here with FMbatch on a --you guessed it-- Solaris machine. > >We check them out of source control and build them automagically, but as >you can see from the noise below a book I just created from scratch on my >Windows machine is not playing nice with FMbatch. > >Earlier I had an error on pg 18. I saved the book as MIF (exported >really). Then opened the MIF and saved as Frame 8 to dispell the demons >as it were. > >So, it looks like the bad behavior has moved to p 3, which is kind of a >good thing. --I guess Adobe must build its books in reverse. Anyhow, if >you have any ideas what might be plaguing me here please give a >shout. I'm going home. > >Reid > >CID support library initialization completed. >%%[ Warning: Empty job. No PDF file produced. ] %% >Normalizer 8.0. >UsePrologue is false. >%%[ Warning: Empty job. No PDF file produced. ] %% >Done >%%[ Error: undefined; OffendingCommand: pdfmark; ErrorInfo: Rect ]%% >Stack: >/ANN >/Link >/Subtype >/G3.998318 >/D >/GoToR >... Is it possible that you are using the initial release of FM8.0? The initial FM8.0 release handled link information incorrectly (missing two angle brackets in the definition of the link's action in the PS file). Check whether you can update FM8 (applying available patches). If not, as a workaround: turn Tagged PDF on (without selecting specific tags) in FM's PDF Setup dialog box [note: I don't generally recommend producing "Tagged PDFs" from FrameMaker] Shlomo Perets MicroType, http://www.microtype.com <http://www.microtype.com/> FrameMaker/Acrobat training & consulting * FM-to-Acrobat TimeSavers/Assistants Template Design, Single Sourcing, FM-to-PDF & Acrobat courses ___ You are currently subscribed to Framers as florama at westinghouse.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/florama%40westinghouse.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
PDF create with FMbatch fails --doh!
Hello Framers, We build our books here with FMbatch on a --you guessed it-- Solaris machine. We check them out of source control and build them automagically, but as you can see from the noise below a book I just created from scratch on my Windows machine is not playing nice with FMbatch. Earlier I had an error on pg 18. I saved the book as MIF (exported really). Then opened the MIF and saved as Frame 8 to dispell the demons as it were. So, it looks like the bad behavior has moved to p 3, which is kind of a good thing. --I guess Adobe must build its books in reverse. Anyhow, if you have any ideas what might be plaguing me here please give a shout. I'm going home. Reid CID support library initialization completed. %%[ Warning: Empty job. No PDF file produced. ] %% Normalizer 8.0. UsePrologue is false. %%[ Warning: Empty job. No PDF file produced. ] %% Done %%[ Error: undefined; OffendingCommand: pdfmark; ErrorInfo: Rect ]%% Stack: /ANN /Link /Subtype /G3.998318 /D /GoToR /S /Action /Type -dict- /Action [0 0 0] /Border [72 608 540 622] /Rect -mark- %%[ Flushing: rest of job (to end-of-file) will be ignored ]%% ExternalCommand on page 3 :F %%[ Warning: PostScript error. No PDF file produced. ] %% Normalizer job 2 failed (2) -- aborting 1671168 bytes read from file /export/home/agreenwell/Documents/Doc/trunk/src/sw_install_gd/ISC_install.tps: FAILED Done ___ 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.
PDF create with FMbatch fails --doh!
Hello Framers, We build our books here with FMbatch on a --you guessed it-- Solaris machine. We check them out of source control and build them automagically, but as you can see from the noise below a book I just created from scratch on my Windows machine is not playing nice with FMbatch. Earlier I had an error on pg 18. I saved the book as MIF (exported really). Then opened the MIF and saved as Frame 8 to dispell the demons as it were. So, it looks like the bad behavior has moved to p 3, which is kind of a good thing. --I guess Adobe must build its books in reverse. Anyhow, if you have any ideas what might be plaguing me here please give a shout. I'm going home. Reid CID support library initialization completed. %%[ Warning: Empty job. No PDF file produced. ] %% Normalizer 8.0. UsePrologue is false. %%[ Warning: Empty job. No PDF file produced. ] %% Done %%[ Error: undefined; OffendingCommand: pdfmark; ErrorInfo: Rect ]%% Stack: /ANN /Link /Subtype /G3.998318 /D /GoToR /S /Action /Type -dict- /Action [0 0 0] /Border [72 608 540 622] /Rect -mark- %%[ Flushing: rest of job (to end-of-file) will be ignored ]%% ExternalCommand on page 3 :F %%[ Warning: PostScript error. No PDF file produced. ] %% Normalizer job 2 failed (2) -- aborting 1671168 bytes read from file /export/home/agreenwell/Documents/Doc/trunk/src/sw_install_gd/ISC_install.tps: FAILED Done
Drooping registered trademarks in cross references
Hi Framers, I have a cross referenced heading. The heading includes a variable that includes a registered trademark. The problem is that the trademark in the crossreference droops after I perform a book update. I suspect Frame converts the character from subscript to normal after I update the book. The variable definition looks like this. Default ¶ FontACMESuperscript®Default ¶ Font Crossreferences in general seem to be quirky with Frame 8. Yes? Frame 8 with all the updates XP sp3 Thanks, Reid ___ 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.
Drooping registered trademarks in cross references
Hi Framers, I have a cross referenced heading. The heading includes a variable that includes a registered trademark. The problem is that the trademark in the crossreference droops after I perform a book update. I suspect Frame converts the character from subscript to normal after I update the book. The variable definition looks like this. ACME? Crossreferences in general seem to be quirky with Frame 8. Yes? Frame 8 with all the updates XP sp3 Thanks, Reid
