Re: radical revamping of techpubs
HA! Quite true! TW's usually also bring an approach that is closer to "green field" than the developers, engineers, etc., can provide. Because they understand how THEY INTEND for it to function and be used, they can be a bit myopic about how what they have CREATED actually plays out. Rene Bill Swallow <[EMAIL PROTECTED]> wrote: I'd say that those are additional skills. What I took Chris' remark to mean is that writers should be there through the entire process, involved with design, so not only do they influence the product design along with the other stakeholders, but also have a means of thoroughly planning the entire documentation effort as part of that product development planning. Let's face it, most tech writers come at a product from a different angle than an engineer or a tester. It may not always be user focused, but it certainly is from a task-based angle. "Is this thing going to be well thought out and therefore easy to explain or is this going to be yet another 100 page install procedure?" ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
radical revamping of techpubs
HA! Quite true! TW's usually also bring an approach that is closer to "green field" than the developers, engineers, etc., can provide. Because they understand how THEY INTEND for it to function and be used, they can be a bit myopic about how what they have CREATED actually plays out. Rene Bill Swallow wrote: I'd say that those are additional skills. What I took Chris' remark to mean is that writers should be there through the entire process, involved with design, so not only do they influence the product design along with the other stakeholders, but also have a means of thoroughly planning the entire documentation effort as part of that product development planning. Let's face it, most tech writers come at a product from a different angle than an engineer or a tester. It may not always be user focused, but it certainly is from a task-based angle. "Is this thing going to be well thought out and therefore easy to explain or is this going to be yet another 100 page install procedure?"
radical revamping of techpubs
I'd say that those are additional skills. What I took Chris' remark to mean is that writers should be there through the entire process, involved with design, so not only do they influence the product design along with the other stakeholders, but also have a means of thoroughly planning the entire documentation effort as part of that product development planning. Let's face it, most tech writers come at a product from a different angle than an engineer or a tester. It may not always be user focused, but it certainly is from a task-based angle. "Is this thing going to be well thought out and therefore easy to explain or is this going to be yet another 100 page install procedure?" On 10/18/07, Rene Stephenson wrote: > Human engineering, customer research prior to design concept, GUI concept > and progression testing, usability testing, quality control, user advocacy, > basic GUI verification and operability (short of rigorous software design > testing)... the list goes on. There are a lot of areas where TWs could ply > their skills, provided a corporation values something other than blind > typists who just write what they're paid to write. Perhaps those areas are > things that TWs should pitch and demonstrate their skills toward. -- Bill Swallow HATT List Owner WWP-Users List Owner Senior Member STC, TechValley Chapter STC Single-Sourcing SIG Manager http://techcommdood.blogspot.com
radical revamping of techpubs
> > The movement toward Extreme Programming and Agile Development is a > case in point; documentation is considered a waste of valuable > developer time, and only needs to be slapped together in minimalist > form at the last minute. That is at odds with the "TW perspective" > of involvement during the entire development process (which is ONLY > appropriate for Waterfall, because everything else changes). > Tosh. http://www.agilemodeling.com/essays/agileModelingXP.htm#Documentation "Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference." Ohhh wait, you mean that internal documentation is a waste of time, not customer facing (and requested) documentation. Right? That'll be why, as one of three technical authors working within an XP driven development team (and I mean within as in sitting alongside, contributing to design discussions, arguing UI points, trying early builds) we are struggling to keep up with the (external) documentation requirements. Gordon This email (and any attachments) is private and confidential, and is intended solely for the addressee. If you have received this communication in error please remove it and inform us via telephone or email. Although we take all possible steps to ensure mail and attachments are free from malicious content, malware and viruses, we cannot accept any responsibility whatsoever for any changes to content outwith our administrative bounds. The views represented within this mail are solely the view of the author and do not reflect the views of the organisation as a whole. Graham Technology plc Registered in Scotland company no. SC143434 Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH http://www.grahamtechnology.com
How would you organize these documents?
Hi, everyone- I am using unstructured FM 7.2 (Windows) to maintain the documentation set for a suite of software products. We have several different customers who each receive a different subset of modules, depending on their business needs. Each module can be customized for each client, so that a client that gets Module A might receive different functionality than another client. In short, each customer receives its "own" version of the software. IOW, Customer 1 gets Software Suite v. 5.6 that includes Module A, C, and E. Customer 2 gets Software Suite v. 5.7 that includes Module A, B, and D. BUT the Module A that Customer 1 gets might be different than the Module A that Customer 2 gets. I started out documenting the "out of the box" settings in the user guides, and then thought I'd just put the differences for each customer into customized Release Notes. However, new customers don't receive any release notes, and isn't it incorrect to send a customer a book describing the functionality and features of Module A when they might not be able to see/use everything documented therein? How would you maintain these files? Conditional text? Separate books? I'm not sure where to begin here. Thanks in advance SWD __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
Creating context sensitive help for applications built using DOT NET studio.
Hi all, Have any of you created .chm files for applications built using the .NET studio? The problem that interests me is the lack of a ui.h file for the context mapping. .NET no longer uses this MFC convention. For the same reason, Microsoft help studio cannot trap HTML help messages for these applications. Any interesting links would be appreciated. Thanks, Paul
Re: radical revamping of techpubs
I'd say that those are additional skills. What I took Chris' remark to mean is that writers should be there through the entire process, involved with design, so not only do they influence the product design along with the other stakeholders, but also have a means of thoroughly planning the entire documentation effort as part of that product development planning. Let's face it, most tech writers come at a product from a different angle than an engineer or a tester. It may not always be user focused, but it certainly is from a task-based angle. "Is this thing going to be well thought out and therefore easy to explain or is this going to be yet another 100 page install procedure?" On 10/18/07, Rene Stephenson <[EMAIL PROTECTED]> wrote: > Human engineering, customer research prior to design concept, GUI concept > and progression testing, usability testing, quality control, user advocacy, > basic GUI verification and operability (short of rigorous software design > testing)... the list goes on. There are a lot of areas where TWs could ply > their skills, provided a corporation values something other than blind > typists who just write what they're paid to write. Perhaps those areas are > things that TWs should pitch and demonstrate their skills toward. -- Bill Swallow HATT List Owner WWP-Users List Owner Senior Member STC, TechValley Chapter STC Single-Sourcing SIG Manager http://techcommdood.blogspot.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
Human engineering, customer research prior to design concept, GUI concept and progression testing, usability testing, quality control, user advocacy, basic GUI verification and operability (short of rigorous software design testing)... the list goes on. There are a lot of areas where TWs could ply their skills, provided a corporation values something other than blind typists who just write what they're paid to write. Perhaps those areas are things that TWs should pitch and demonstrate their skills toward. Rene Stephenson Bill Swallow <[EMAIL PROTECTED]> wrote: Agreed. I'm surprised this isn't a more common practice. On 10/18/07, Chris Borokowski wrote: > What makes more sense in my mind is for technical writers to expand > their role to the life-cycle of the product, from conception to > maintenance, by investing in understanding interaction design/interface > design, quality control and user advocacy positions. -- Bill Swallow HATT List Owner WWP-Users List Owner Senior Member STC, TechValley Chapter STC Single-Sourcing SIG Manager http://techcommdood.blogspot.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/rinnie1%40yahoo.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
radical revamping of techpubs
Human engineering, customer research prior to design concept, GUI concept and progression testing, usability testing, quality control, user advocacy, basic GUI verification and operability (short of rigorous software design testing)... the list goes on. There are a lot of areas where TWs could ply their skills, provided a corporation values something other than blind typists who just write what they're paid to write. Perhaps those areas are things that TWs should pitch and demonstrate their skills toward. Rene Stephenson Bill Swallow wrote: Agreed. I'm surprised this isn't a more common practice. On 10/18/07, Chris Borokowski wrote: > What makes more sense in my mind is for technical writers to expand > their role to the life-cycle of the product, from conception to > maintenance, by investing in understanding interaction design/interface > design, quality control and user advocacy positions. -- Bill Swallow HATT List Owner WWP-Users List Owner Senior Member STC, TechValley Chapter STC Single-Sourcing SIG Manager http://techcommdood.blogspot.com ___ You are currently subscribed to Framers as rinnie1 at yahoo.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/rinnie1%40yahoo.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
I agree with Gordon. Infact, there is requirement for more and more documentation. I see that every new user interface comes with its own set of tutorials. Smile makes you more close; try it Thanks and Regards, N. Jain Writer 91-9810676241 http://www.neerajjain8.com | http://neerajjain8.rediffiland.com - Original Message From: Gordon McLean <[EMAIL PROTECTED]> Cc: framers@lists.frameusers.com Sent: Thursday, October 18, 2007 8:16:44 PM Subject: RE: radical revamping of techpubs > > The movement toward Extreme Programming and Agile Development is a > case in point; documentation is considered a waste of valuable > developer time, and only needs to be slapped together in minimalist > form at the last minute. That is at odds with the "TW perspective" > of involvement during the entire development process (which is ONLY > appropriate for Waterfall, because everything else changes). > Tosh. http://www.agilemodeling.com/essays/agileModelingXP.htm#Documentation "Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference." Ohhh wait, you mean that internal documentation is a waste of time, not customer facing (and requested) documentation. Right? That'll be why, as one of three technical authors working within an XP driven development team (and I mean within as in sitting alongside, contributing to design discussions, arguing UI points, trying early builds) we are struggling to keep up with the (external) documentation requirements. Gordon This email (and any attachments) is private and confidential, and is intended solely for the addressee. If you have received this communication in error please remove it and inform us via telephone or email. Although we take all possible steps to ensure mail and attachments are free from malicious content, malware and viruses, we cannot accept any responsibility whatsoever for any changes to content outwith our administrative bounds. The views represented within this mail are solely the view of the author and do not reflect the views of the organisation as a whole. Graham Technology plc Registered in Scotland company no. SC143434 Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH http://www.grahamtechnology.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/neerajjain8%40yahoo.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
radical revamping of techpubs
I agree with Gordon. Infact, there is requirement for more and more documentation. I see that every new user interface comes with its own set of tutorials. Smile makes you more close; try it Thanks and Regards, N. Jain Writer 91-9810676241 http://www.neerajjain8.com | http://neerajjain8.rediffiland.com - Original Message From: Gordon McLean Cc: framers at lists.frameusers.com Sent: Thursday, October 18, 2007 8:16:44 PM Subject: RE: radical revamping of techpubs > > The movement toward Extreme Programming and Agile Development is a > case in point; documentation is considered a waste of valuable > developer time, and only needs to be slapped together in minimalist > form at the last minute. That is at odds with the "TW perspective" > of involvement during the entire development process (which is ONLY > appropriate for Waterfall, because everything else changes). > Tosh. http://www.agilemodeling.com/essays/agileModelingXP.htm#Documentation "Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference." Ohhh wait, you mean that internal documentation is a waste of time, not customer facing (and requested) documentation. Right? That'll be why, as one of three technical authors working within an XP driven development team (and I mean within as in sitting alongside, contributing to design discussions, arguing UI points, trying early builds) we are struggling to keep up with the (external) documentation requirements. Gordon This email (and any attachments) is private and confidential, and is intended solely for the addressee. If you have received this communication in error please remove it and inform us via telephone or email. Although we take all possible steps to ensure mail and attachments are free from malicious content, malware and viruses, we cannot accept any responsibility whatsoever for any changes to content outwith our administrative bounds. The views represented within this mail are solely the view of the author and do not reflect the views of the organisation as a whole. Graham Technology plc Registered in Scotland company no. SC143434 Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH http://www.grahamtechnology.com ___ You are currently subscribed to Framers as neerajjain8 at yahoo.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/neerajjain8%40yahoo.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info. __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
Radical revamping of techpubs
I would maintain, that it's impossible to facilitate knowledge transfer without good style, form and consistency, but I would agree that without clear writing, it hardly matters how good it looks. You will never achieve the perfect interface. It's not going to happen. Your grandmother is still going to be confused by what seems inherently obvious to you. You can anticipate the needs, aptitude, learning style and so forth of every user in the customer base. It's simply an unreachable goal, especially in a sophisticated software package developed by multiple developers under commercial and time pressure. Software isn't produced in a vacuum by robots, it's produced by humans with lots on their plates. What we can control is that we can produce documentation that's clear, concise, well written, well organized, and easy to navigate. If we as tech writers aim for this goal, then I think we can at least satisfy a good number of users, help them solve their issues or use the software, reduce calls to customer support and help make the product better. The other stuff is pie in the sky to me and not likely to happen any time soon. Ron Ron Miller Freelance Technology Writing Since 1988 Contributing Editor, EContent Magazine email: ronsmiller at ronsmiller.com blog: http://byronmiller.typepad.com web: http://www.ronsmiller.com Winner of the 2006 and 2007 Apex Award for Publication Excellence/ Feature Writing On Oct 18, 2007, at 11:43 AM, Technical Writer wrote: > > Technical writing, specifically end-user documentation of software > applications, is perceived by the majority of producers as "less > than useful" and, in general, a waste of money, time, and effort. > Similarly, the TW's view that they are "adding value" to a product > may be just as impoverished. > > Documentation is not used by the end-user because it is awkward, > poorly organized, and in many cases, indecipherable for a user > seeking task-accomplishment assistance. Linux is a primary example; > despite some of the most dedicated, motivated developers on the > planet, and droves of TWs spending endless amounts of time creating > "tutorials," introductions," and "documentation," (along with a > massive PR pitch by IBM a few years back), Linux languishes. Users > avoid it because it is "too difficult to learn." > > The underlying cause begs exploration, and is at the heart of > technical documentation; does the TW really want the witless user > to understand what the TW finds conceptually difficult? Or is there > the same tendency in TW that is found in academia--"I took years to > learn this, and you expect me to tell you how to do it in half-an- > hour?" > > I am not suggesting for a minute that the process is planned, or > even that the TW is aware of it. I am suggesting that the > underlying premise of technical documentation is not > "documentation" (as in "creating a record of"), but knowledge > transfer. It is in the area of knowledge transfer that TW comes up > short. Of all the software documentation available on October 18, > 2007, how many pieces are considered easy-to-use by users? > > What I suggest is not a simplistic condemnation of TW, or TWs. What > I suggest is that the underlying premises of TW may be > impoverished, and suffer the same weakness as academic > "instruction." That is, replaying the one-to-many lecture style of > Aristotle on the computer screen, in the mistaken belief that a > user really cares whether every i is dotted and every t crossed, or > that a consistent style is used for all code samples, and a > consistent voice is used for all explanations. > > Finally, the reason that user interfaces in software applications > require extensive documentation is a failure in the design and > programming stage, not in the documentation stage. If the interface > were competently designed, it should be "intuitive" to use, and > require only minimalist documentation. If there is a future for TW, > it lies in the area of facilitating knowledge transfer, rather than > an obsession with style, form, and consistency. > > > _ > Climb to the top of the charts! Play Star Shuffle: the word > scramble challenge with star power. > http://club.live.com/star_shuffle.aspx? > icid=starshuffle_wlmailtextlink_oct___ > > > > You are currently subscribed to Framers as ronsmiller at comcast.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/ > ronsmiller%40comcast.net > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info.
Radical revamping of techpubs
Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished. Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. Linux is a primary example; despite some of the most dedicated, motivated developers on the planet, and droves of TWs spending endless amounts of time creating "tutorials," introductions," and "documentation," (along with a massive PR pitch by IBM a few years back), Linux languishes. Users avoid it because it is "too difficult to learn." The underlying cause begs exploration, and is at the heart of technical documentation; does the TW really want the witless user to understand what the TW finds conceptually difficult? Or is there the same tendency in TW that is found in academia--"I took years to learn this, and you expect me to tell you how to do it in half-an-hour?" I am not suggesting for a minute that the process is planned, or even that the TW is aware of it. I am suggesting that the underlying premise of technical documentation is not "documentation" (as in "creating a record of"), but knowledge transfer. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users? What I suggest is not a simplistic condemnation of TW, or TWs. What I suggest is that the underlying premises of TW may be impoverished, and suffer the same weakness as academic "instruction." That is, replaying the one-to-many lecture style of Aristotle on the computer screen, in the mistaken belief that a user really cares whether every i is dotted and every t crossed, or that a consistent style is used for all code samples, and a consistent voice is used for all explanations. Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency. _ Climb to the top of the charts!? Play Star Shuffle:? the word scramble challenge with star power. http://club.live.com/star_shuffle.aspx?icid=starshuffle_wlmailtextlink_oct
Boolean condition expression problems in FM 8
Hi, Sorry, 2 more issues: o I noticed that boolean expressions set in one file of a book are not overridden when I set "Show All" for the whole book. In this file still "Show as per Expression" is set. o When I want to set boolean expressions for the whole book, not all available conditions are shown in the boolean expression window. In the "Show/Hide Conditional Text" all conditions are shown correctly. Best regards Winfried > We have a "comment" condition which should be hidden in the > final document and other conditions which should be shown. > However, here I ran into problems, when I have text which > has "comment" and another condition applied, and text with > "comment" should be hidden. I tried this: > > o "draft"OR"print"OR"nursecall"ORNOT"comment" -> Text which > has "nursecall" and "comment" assigned is shown. > > o "nurse call"ANDNOT"comment"OR"draft"OR"print" -> Text which > has "nursecall" and "comment" assigned is hidden. That's > exactly what I want and it works. Very good. However I cannot > explain why. Obviously the order is important. But I do not > want to try all possibilities. > In my oppinion I would need the option to group the single > elements in this expression. But that's not allowed. > > > > And other condition issues: > > o I have to close all condition windows when I want to do > something else. I cannot leave them open as before. > > o When I select "Show All" and "Set" and then again an expression > my latest expression got lost. > > o The FM documentation is not correct when it says: 5. Click > the AND, OR, or NOT button. > When I need "NOT" the result must be ANDNOT or ORNOT. > I miss examples. > > And another minor annoyance: When in FM e.g. the paragraph > designer was active and I switch to another application and go > back to FM, FM 8 displays now only the paragraph designer. The > whole FM window should be shown. > > Best regards > > Winfried
Boolean condition expression problems in FM 8
Hi, We have a "comment" condition which should be hidden in the final document and other conditions which should be shown. However, here I ran into problems, when I have text which has "comment" and another condition applied, and text with "comment" should be hidden. I tried this: o "draft"OR"print"OR"nursecall"ORNOT"comment" -> Text which has "nursecall" and "comment" assigned is shown. o "nurse call"ANDNOT"comment"OR"draft"OR"print" -> Text which has "nursecall" and "comment" assigned is hidden. That's exactly what I want and it works. Very good. However I cannot explain why. Obviously the order is important. But I do not want to try all possibilities. In my oppinion I would need the option to group the single elements in this expression. But that's not allowed. And other condition issues: o I have to close all condition windows when I want to do something else. I cannot leave them open as before. o When I select "Show All" and "Set" and then again an expression my latest expression got lost. o The FM documentation is not correct when it says: 5. Click the AND, OR, or NOT button. When I need "NOT" the result must be ANDNOT or ORNOT. I miss examples. And another minor annoyance: When in FM e.g. the paragraph designer was active and I switch to another application and go back to FM, FM 8 displays now only the paragraph designer. The whole FM window should be shown. Best regards Winfried
footnote problem
Bodvar Bjorgvinsson wrote: > My walnut is telling me that a footnote is a footnote and things that > do not fit within the majority of a page as allowed in FrameMaker must > be something else, like an end note or just as an "insert" (not in the > FM way) that is just shown indented and/or in smaller type in direct > continuation of the subject section/part/paragraph. > ...and if you checked it, you'd find the Chicago Manual of Style telling you pretty much the same thing. Tina, you might want to have a look through section 15 of CMOS, especially "Extensive versus Excessive Documentation" beginning at 15.15 and Footnotes beginning at 15.41. (14th Edition; the 15th ed. on line puts this info in section 16.) These sections contain a good description of the problem your author is creating, in terms of book layout and typesetting (i.e., not particular to FM or any other software) and cogent arguments that you might deliver to him suggesting a different approach. There are also suggestions on how to reduce the size of long footnotes if there is simply no way to avoid them. HTH, -- Stuart Rogers Technical Communicator Phoenix Geophysics Limited Toronto, ON, Canada +1 (416) 491-7340 x 325 srogers phoenix-geophysics com "On the contrary." -- Henrik Ibsen (last words, after a nurse said he "seemed a little better.")
Footnote problem--long footnotes
On 17 Oct 2007 at 12:59, Tina Ricks wrote: > Has anyone seen this? Any ideas about how to deal with long footnotes in > Frame other than go back to the author and tell him to rewrite? Well, I think the author will insist... So I would try a quirk, because the whole text seems to be a quirk anyhow: - Put the text of the extra long footnote aside - At the page place only an introductory part of this long footnote with a cross reference to the full text: 127)Hecate est Iovis et Latonae filia, soror Apollinis. Est tricopor et triceps, magicarum artium magistra ac fascinationum praeses, cinctra latrantium canum turma. (see complete footnote at page 312). - Place this awful footnote in an appendix, where you probably have other strange things also. Klaus Daube Docu + Design Daube; Sch?racher 11; CH-8053 Z?rich Technical documentation & consultancy; On-line and paper Phone: +41-44-422 86 25 FAX: +41-44-422 82 78 E-mail: ddd at daube.ch Web: www.daube.ch/
RE: Radical revamping of techpubs
Lots to digest here: Technical Writer <[EMAIL PROTECTED]> wrote: Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. This is observable. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished. I certainly hope not. If it is, TW's are forgetting some key ingredients of good writing: relevance, usability, and accessibility. (By accessibility in this instance I don't mean as relating to accomodating certain challenges the user may have; I mean the ability of the user to actually FIND the information they seek, assuming that the information is there. Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. People who aren't avid readers in general don't turn to books for answers, but an increasing number of users do try to find answers online, either via the F1 key or an internet access point. The whole reason I got into TW in the first place is that I was extremely frustrated as a user of the books for the programs necessary for my job at the time. I was marking up the books with "no, it really works like x" and catching typos and grammar errors. Now that I've spent over a decade in TW, I can honestly say that a lot of the reason for the user's frustration is probably rooted in the excruciatingly short timelines required of most TWs, as well as the all-too-common presumption by the TW and/or their management that an review by a qualified editor is a "luxury." There are many contributing factors. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users? Document usability and readability enable or incumber knowledge transfer at least as much as relevance and organization of the content do. However, of the scores of TWs that I've worked with over the years, several with at least 25 years in the field, many are completely unfamiliar with basic concepts of how to make clear, concise information that is easy to find and easy to read and actually relevant to the user. It's been my experience that only about 1/4 of the TWs I've met "get" those concepts. Most of them are really good at understanding their subject matter and getting the point across to the reader, but many get too many tangiential factors involved or fail to understand how the user approaches the product and, therefore, fail to organize the information in a way that the user needs it presented, much less index it with terms the user would seek. There are a few companies that are customer-focused enough to get the TW's efforts into some doc usability scenarios, but these companies seem more the exception than the rule...at least in telecom. Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. In telecom, even the most intuitive user interfaces require documentation to explain the system ramifications and configuration options available with various combinations of settings. Some of it could be converted to field-level on screen "what's this" roll-over text, but a lot of it requires interrelational understanding as applied to various scenarios and goals. No screen, regardless of how intuitively it is designed, can convey that information...to the best of my understanding or estimation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency. Yes, the future of TW does rest *partly* in facilitating knowledge transfer. It also includes knowledge management and creating and maintaining a bridge between what the customer does with the products and what the company provides as products for the customer. My 2¢ Rene Stephenson ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Radical revamping of techpubs
Lots to digest here: Technical Writer wrote: Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. This is observable. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished. I certainly hope not. If it is, TW's are forgetting some key ingredients of good writing: relevance, usability, and accessibility. (By accessibility in this instance I don't mean as relating to accomodating certain challenges the user may have; I mean the ability of the user to actually FIND the information they seek, assuming that the information is there. Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. People who aren't avid readers in general don't turn to books for answers, but an increasing number of users do try to find answers online, either via the F1 key or an internet access point. The whole reason I got into TW in the first place is that I was extremely frustrated as a user of the books for the programs necessary for my job at the time. I was marking up the books with "no, it really works like x" and catching typos and grammar errors. Now that I've spent over a decade in TW, I can honestly say that a lot of the reason for the user's frustration is probably rooted in the excruciatingly short timelines required of most TWs, as well as the all-too-common presumption by the TW and/or their management that an review by a qualified editor is a "luxury." There are many contributing factors. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users? Document usability and readability enable or incumber knowledge transfer at least as much as relevance and organization of the content do. However, of the scores of TWs that I've worked with over the years, several with at least 25 years in the field, many are completely unfamiliar with basic concepts of how to make clear, concise information that is easy to find and easy to read and actually relevant to the user. It's been my experience that only about 1/4 of the TWs I've met "get" those concepts. Most of them are really good at understanding their subject matter and getting the point across to the reader, but many get too many tangiential factors involved or fail to understand how the user approaches the product and, therefore, fail to organize the information in a way that the user needs it presented, much less index it with terms the user would seek. There are a few companies that are customer-focused enough to get the TW's efforts into some doc usability scenarios, but these companies seem more the exception than the rule...at least in telecom. Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. In telecom, even the most intuitive user interfaces require documentation to explain the system ramifications and configuration options available with various combinations of settings. Some of it could be converted to field-level on screen "what's this" roll-over text, but a lot of it requires interrelational understanding as applied to various scenarios and goals. No screen, regardless of how intuitively it is designed, can convey that information...to the best of my understanding or estimation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency. Yes, the future of TW does rest *partly* in facilitating knowledge transfer. It also includes knowledge management and creating and maintaining a bridge between what the customer does with the products and what the company provides as products for the customer. My 2? Rene Stephenson
radical revamping of techpubs
Agreed. I'm surprised this isn't a more common practice. On 10/18/07, Chris Borokowski wrote: > What makes more sense in my mind is for technical writers to expand > their role to the life-cycle of the product, from conception to > maintenance, by investing in understanding interaction design/interface > design, quality control and user advocacy positions. -- Bill Swallow HATT List Owner WWP-Users List Owner Senior Member STC, TechValley Chapter STC Single-Sourcing SIG Manager http://techcommdood.blogspot.com
radical revamping of techpubs
On Oct 11, 2007, at 10:23 AM, Technical Writer wrote: > > The trend has been in that direction since the dotcom bust, when a > number of (formerly) highly paid developers found a comfortable job > writing help files more appealing than unemployment or stocking the > shelves at Wal-Mart. If they have writing skills, then they can make a living as a tech writer, and more power to them, but just because they are technical certainly doesn't mean they can write. > > While it is easy for technical writers to convince themselves of > the value of what they do, the simple truth is that many users lack > the linguistic and cognitive sophistication to distinguish between > "good" writing and "mediocre" writing. I'm sorry, but that's just a gross generalization and there's no way you could realistically back up the statement. > > Similarly, it is easy for technical writers to believe they are > documenting the software, when in fact they are only documenting > the interface. The trend in development is to make the interface > more intuitive, hence easier to use; if the interface requires > extensive documentation about how to use it, it is a failure of > design, not of documentation. That follows the way the overwhelming > majority of users actually interact with software--they start it > up, click a few buttons, and generally try to figure out how it > works. For a well-designed user interface, that should be enough to > get started. Should be, but for the majority of users in the world, it's not that simple. My experience is that you are making a huge mistake if you assume your users have the same level of computer aptitude that you and your colleagues have. Of course, it all depends on audience, but in a typical commercial software program, I believe you have to document to the lowest common denominator and that means assuming little or no computer skills. If you want proof of this, look not further than Office 2007 with its radical interface redesign. In theory, that means it should be easier to use, but in practice, you have to learn where all the tools are after years of doing it another way. Without good training and documentation, the average user who has been using Word with a menu bar/toolbar metaphor for umpteen years is going to have a very rough go trying to find his/her way around. Heck, I'm an experienced user and I find it maddening. > > The movement toward Extreme Programming and Agile Development is a > case in point; documentation is considered a waste of valuable > developer time, and only needs to be slapped together in minimalist > form at the last minute. That is at odds with the "TW perspective" > of involvement during the entire development process (which is ONLY > appropriate for Waterfall, because everything else changes). > > I can't speak to this because I don't delve into programming and development theory, but I can say that as a tech writer with 20 years experience, that one of my big value adds is acting as the voice of the end user. Developing involves a series of choices often made in haste, and often involving a number of people working separately on different pieces. I've found that as a person looking at the entire program, and carefully documenting how it works, I can act not only as another QA piece, but also recognize inconsistencies and bad choices and I can make suggestions for improving the program. If you bring me in at the end of the process, there is less time to react to these types of changes. If I'm involved from the beginning, I can act as another set of eyes. > Because there is already a dichotomy between the GUI developers and > the "real" programmers, it is a small step to realize that the best > people to provide the minimalist documentation necessary to use the > interface are the developers of that interface. If the interface > requires more than minimalist documentation, the core problem is > the failure of the design, not a lack of technical writers. > Minimalist documentation should be based on the remarks (in the > code) of the developers, not a secondary understanding of a > technical writer acting as a third party. Yea, in theory, maybe, but in reality, you can't know if the GUI is dead easy to use, because you can't possibly assume you know the computer aptitude of your entire customer base. In my experience, people have very little computer savvy and mostly know only how to use the bundle of programs they use regularly. If you take them outside of that comfort zone, it's like starting from scratch. > > If a technical writer wants to document software, he or she should > learn to program competently. Similarly, a GUI developer who wants > to stay employed should learn the basic skill set needed to convert > remarks in the code to help files. The dichotomy between developer > and writer is artificial, and not
RE: radical revamping of techpubs
> I've seen XP happening in a number of companies that are now > dead. Think of it as evolution in action. I've also seen companies that do not use Agile go out of business, so maybe Agile is not what drove them out of business. > XP and Agile are excuses for bad behavior. "We're manly > men who code brilliantly; we don't need documentation > because our code is perfect and if the users don't understand > our godlike design, that's their problem." XP and Agile will > get code out the door and it may even be good code (occasionally), > but it ignores the idea that 90% of programming is maintenance... > and without internal documentation or process, you have no history. Nothing is going to be all go with no bad...it's a balancing act. The primary purpose of Agile is instead of develop, develop, develop, develop, develop, show customer, crap-got it wrong, You develop, show customer, modify, develop, show customer, modify, develop, show customer, modify, present to customer "Hey!, it's exactly what I want. As far as documentation, NOTHING in Agile has any impact on the amount of deliverable documentation (user guides, help, etc). It's all geared toward developer documentation, and even then, the idea is not documentation that's not needed. If a document is really needed, it stays. > our godlike design, that's their problem." XP and Agile will > get code out the door and it may even be good code (occasionally), My company is embracing Agile. Is it working? Who knows. I do know this. As a company, we run a number of dashboards that give progress status. Since we embraced Agile, the number of software bugs has started to decline while the number of customers is climbing. Who knows what it's due to, but it's heading in the right direction. John Posada Senior Technical Writer "They say everyone needs goals. Mine is to live forever. So far, so good." ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
radical revamping of techpubs
> I've seen XP happening in a number of companies that are now > dead. Think of it as evolution in action. I've also seen companies that do not use Agile go out of business, so maybe Agile is not what drove them out of business. > XP and Agile are excuses for bad behavior. "We're manly > men who code brilliantly; we don't need documentation > because our code is perfect and if the users don't understand > our godlike design, that's their problem." XP and Agile will > get code out the door and it may even be good code (occasionally), > but it ignores the idea that 90% of programming is maintenance... > and without internal documentation or process, you have no history. Nothing is going to be all go with no bad...it's a balancing act. The primary purpose of Agile is instead of develop, develop, develop, develop, develop, show customer, crap-got it wrong, You develop, show customer, modify, develop, show customer, modify, develop, show customer, modify, present to customer "Hey!, it's exactly what I want. As far as documentation, NOTHING in Agile has any impact on the amount of deliverable documentation (user guides, help, etc). It's all geared toward developer documentation, and even then, the idea is not documentation that's not needed. If a document is really needed, it stays. > our godlike design, that's their problem." XP and Agile will > get code out the door and it may even be good code (occasionally), My company is embracing Agile. Is it working? Who knows. I do know this. As a company, we run a number of dashboards that give progress status. Since we embraced Agile, the number of software bugs has started to decline while the number of customers is climbing. Who knows what it's due to, but it's heading in the right direction. John Posada Senior Technical Writer "They say everyone needs goals. Mine is to live forever. So far, so good."
footnote problem
My walnut is telling me that a footnote is a footnote and things that do not fit within the majority of a page as allowed in FrameMaker must be something else, like an end note or just as an "insert" (not in the FM way) that is just shown indented and/or in smaller type in direct continuation of the subject section/part/paragraph. I understand the problem, although I have not had to deal with it (other than when the footnote reference is too low on the page for the footnote itself to fit). This problem has come up several times on the list IIRC. I have no other solution than this and, then maybe to cross-reference it. Is this something that can be overridden by a FrameScript? I guess not. Adobe should look into this along with some other quirks, like the feathering problem when you have an anchored frame on a page, and/or balanced columns. Bodvar On 10/18/07, Graeme R Forbes wrote: > Tina wrote: > > "If I take out > the now disappeared long footnote (by deleting the footnote reference in the > text), all the other footnotes go back where they belong" > > Are you sure about this? If there are lots of long notes in the doc > it's very likely that FM has pushed some of them in their entirety > onto the following page. FrameMaker can't split long notes across > pages correctly. Useless behavior which, as Rick said, has been with > us since FM 4 (FM 3 in my experience, and no doubt since FM 1 -- the > footnote facility was programmed to do exactly what it does, by > people who didn't understand how footnotes are supposed to behave). > So you have to break them manually, using text boxes inside anchored > frames for the part of the note that won't fit on the page with the > reference number in the main text. Or else make them all endnotes by > the ugly method described in the user manual, which I once automated > in Applescript. But endnotes are so reader-hostile that it's worth > slogging thro' the manual process. > > Graeme Forbes > ___ > > > 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. >
Re: Radical revamping of techpubs
I would maintain, that it's impossible to facilitate knowledge transfer without good style, form and consistency, but I would agree that without clear writing, it hardly matters how good it looks. You will never achieve the perfect interface. It's not going to happen. Your grandmother is still going to be confused by what seems inherently obvious to you. You can anticipate the needs, aptitude, learning style and so forth of every user in the customer base. It's simply an unreachable goal, especially in a sophisticated software package developed by multiple developers under commercial and time pressure. Software isn't produced in a vacuum by robots, it's produced by humans with lots on their plates. What we can control is that we can produce documentation that's clear, concise, well written, well organized, and easy to navigate. If we as tech writers aim for this goal, then I think we can at least satisfy a good number of users, help them solve their issues or use the software, reduce calls to customer support and help make the product better. The other stuff is pie in the sky to me and not likely to happen any time soon. Ron Ron Miller Freelance Technology Writing Since 1988 Contributing Editor, EContent Magazine email: [EMAIL PROTECTED] blog: http://byronmiller.typepad.com web: http://www.ronsmiller.com Winner of the 2006 and 2007 Apex Award for Publication Excellence/ Feature Writing On Oct 18, 2007, at 11:43 AM, Technical Writer wrote: Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished. Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. Linux is a primary example; despite some of the most dedicated, motivated developers on the planet, and droves of TWs spending endless amounts of time creating "tutorials," introductions," and "documentation," (along with a massive PR pitch by IBM a few years back), Linux languishes. Users avoid it because it is "too difficult to learn." The underlying cause begs exploration, and is at the heart of technical documentation; does the TW really want the witless user to understand what the TW finds conceptually difficult? Or is there the same tendency in TW that is found in academia--"I took years to learn this, and you expect me to tell you how to do it in half-an- hour?" I am not suggesting for a minute that the process is planned, or even that the TW is aware of it. I am suggesting that the underlying premise of technical documentation is not "documentation" (as in "creating a record of"), but knowledge transfer. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users? What I suggest is not a simplistic condemnation of TW, or TWs. What I suggest is that the underlying premises of TW may be impoverished, and suffer the same weakness as academic "instruction." That is, replaying the one-to-many lecture style of Aristotle on the computer screen, in the mistaken belief that a user really cares whether every i is dotted and every t crossed, or that a consistent style is used for all code samples, and a consistent voice is used for all explanations. Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency. _ Climb to the top of the charts! Play Star Shuffle: the word scramble challenge with star power. http://club.live.com/star_shuffle.aspx? icid=starshuffle_wlmailtextlink_oct___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/ ronsmiller%40comcast.net Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.c
RE: Radical revamping of techpubs
There's other problems with Linux, and this article says it all: http://www.pcmag.com/article2/0,2704,2197786,00.asp I am agnostic about Linux. It does some things well. It's not ready for the desktop because installation of the OS, and then software, is often a massive PITA. With Windows, it just works. That's what the end user wants. A few of them want Macs, but most people shy away from companies as erratic and expensive and often destructive as Apple. I think TWs are in a different bind: interfaces are standardizing. What was once rare knowledge, like using internet apps and protocols, is now standard knowledge. We're going to have to work harder to make ourselves more useful, and not just show up to WTFM at the end of a project. The sensible goal I think is to make ourselves into user interaction experts. We know how to explain stuff to users, so now we work the other end of the process and explain users to those who make the stuff. Yes, it may require more training, but these days if you want to be considered professional as a new worker, you need that graduate degree anyway. I've now said it a few times, so it's probably appropriate to sit back and wait for the next ten years until the truth of this becomes obvious. --- Technical Writer <[EMAIL PROTECTED]> wrote: > Documentation is not used by the end-user because it is awkward, > poorly organized, and in many cases, indecipherable for a user > seeking task-accomplishment assistance. Linux is a primary example; > despite some of the most dedicated, motivated developers on the > planet, and droves of TWs spending endless amounts of time creating > "tutorials," introductions," and "documentation," (along with a > massive PR pitch by IBM a few years back), Linux languishes. Users > avoid it because it is "too difficult to learn." > > The underlying cause begs exploration, and is at the heart of > technical documentation; does the TW really want the witless user to > understand what the TW finds conceptually difficult? http://technical-writing.dionysius.com/ technical writing | consulting | development __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Radical revamping of techpubs
There's other problems with Linux, and this article says it all: http://www.pcmag.com/article2/0,2704,2197786,00.asp I am agnostic about Linux. It does some things well. It's not ready for the desktop because installation of the OS, and then software, is often a massive PITA. With Windows, it just works. That's what the end user wants. A few of them want Macs, but most people shy away from companies as erratic and expensive and often destructive as Apple. I think TWs are in a different bind: interfaces are standardizing. What was once rare knowledge, like using internet apps and protocols, is now standard knowledge. We're going to have to work harder to make ourselves more useful, and not just show up to WTFM at the end of a project. The sensible goal I think is to make ourselves into user interaction experts. We know how to explain stuff to users, so now we work the other end of the process and explain users to those who make the stuff. Yes, it may require more training, but these days if you want to be considered professional as a new worker, you need that graduate degree anyway. I've now said it a few times, so it's probably appropriate to sit back and wait for the next ten years until the truth of this becomes obvious. --- Technical Writer wrote: > Documentation is not used by the end-user because it is awkward, > poorly organized, and in many cases, indecipherable for a user > seeking task-accomplishment assistance. Linux is a primary example; > despite some of the most dedicated, motivated developers on the > planet, and droves of TWs spending endless amounts of time creating > "tutorials," introductions," and "documentation," (along with a > massive PR pitch by IBM a few years back), Linux languishes. Users > avoid it because it is "too difficult to learn." > > The underlying cause begs exploration, and is at the heart of > technical documentation; does the TW really want the witless user to > understand what the TW finds conceptually difficult? http://technical-writing.dionysius.com/ technical writing | consulting | development __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
RE: Radical revamping of techpubs
Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished. Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. Linux is a primary example; despite some of the most dedicated, motivated developers on the planet, and droves of TWs spending endless amounts of time creating "tutorials," introductions," and "documentation," (along with a massive PR pitch by IBM a few years back), Linux languishes. Users avoid it because it is "too difficult to learn." The underlying cause begs exploration, and is at the heart of technical documentation; does the TW really want the witless user to understand what the TW finds conceptually difficult? Or is there the same tendency in TW that is found in academia--"I took years to learn this, and you expect me to tell you how to do it in half-an-hour?" I am not suggesting for a minute that the process is planned, or even that the TW is aware of it. I am suggesting that the underlying premise of technical documentation is not "documentation" (as in "creating a record of"), but knowledge transfer. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users? What I suggest is not a simplistic condemnation of TW, or TWs. What I suggest is that the underlying premises of TW may be impoverished, and suffer the same weakness as academic "instruction." That is, replaying the one-to-many lecture style of Aristotle on the computer screen, in the mistaken belief that a user really cares whether every i is dotted and every t crossed, or that a consistent style is used for all code samples, and a consistent voice is used for all explanations. Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency. _ Climb to the top of the charts! Play Star Shuffle: the word scramble challenge with star power. http://club.live.com/star_shuffle.aspx?icid=starshuffle_wlmailtextlink_oct___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
radical revamping of techpubs
XP and Agile are excuses for bad behavior. "We're manly men who code brilliantly; we don't need documentation because our code is perfect and if the users don't understand our godlike design, that's their problem." XP and Agile will get code out the door and it may even be good code (occasionally), but it ignores the idea that 90% of programming is maintenance... and without internal documentation or process, you have no history. I've seen XP happening in a number of companies that are now dead. Think of it as evolution in action. Yours truly, John Hedtke Author/Consultant/Contract Writer www.hedtke.com <-- website 541-685-5000 (office landline) 541-554-2189 (cell) john at hedtke.com (primary email) johnhedtke at aol.com (secondary email) At 07:46 AM 10/18/2007, Gordon McLean wrote: > > > > The movement toward Extreme Programming and Agile Development is a > > case in point; documentation is considered a waste of valuable > > developer time, and only needs to be slapped together in minimalist > > form at the last minute. That is at odds with the "TW perspective" > > of involvement during the entire development process (which is ONLY > > appropriate for Waterfall, because everything else changes). > > > >Tosh. > >http://www.agilemodeling.com/essays/agileModelingXP.htm#Documentation > >"Outside your extreme programming project, you will probably need >documentation: by all means, write it. Inside your project, there is so much >verbal communication that you may need very little else. Trust yourselves >to know the difference." > >Ohhh wait, you mean that internal documentation is a waste of time, not >customer facing (and requested) documentation. Right? > >That'll be why, as one of three technical authors working within an XP >driven development team (and I mean within as in sitting alongside, >contributing to design discussions, arguing UI points, trying early builds) >we are struggling to keep up with the (external) documentation requirements. > >Gordon > > > > >This email (and any attachments) is private and confidential, and is >intended solely for the >addressee. If you have received this communication in error please >remove it and inform us via >telephone or email. Although we take all possible steps to ensure >mail and attachments >are free from malicious content, malware and viruses, we cannot >accept any responsibility >whatsoever for any changes to content outwith our administrative >bounds. The views represented >within this mail are solely the view of the author and do not >reflect the views of the organisation >as a whole. > >Graham Technology plc >Registered in Scotland company no. SC143434 >Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH > >http://www.grahamtechnology.com > > >___ > > >You are currently subscribed to Framers as john at hedtke.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/john%40hedtke.com > >Send administrative questions to listadmin at frameusers.com. Visit >http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
XP and Agile are excuses for bad behavior. "We're manly men who code brilliantly; we don't need documentation because our code is perfect and if the users don't understand our godlike design, that's their problem." XP and Agile will get code out the door and it may even be good code (occasionally), but it ignores the idea that 90% of programming is maintenance... and without internal documentation or process, you have no history. I've seen XP happening in a number of companies that are now dead. Think of it as evolution in action. Yours truly, John Hedtke Author/Consultant/Contract Writer www.hedtke.com <-- website 541-685-5000 (office landline) 541-554-2189 (cell) [EMAIL PROTECTED] (primary email) [EMAIL PROTECTED] (secondary email) At 07:46 AM 10/18/2007, Gordon McLean wrote: > > The movement toward Extreme Programming and Agile Development is a > case in point; documentation is considered a waste of valuable > developer time, and only needs to be slapped together in minimalist > form at the last minute. That is at odds with the "TW perspective" > of involvement during the entire development process (which is ONLY > appropriate for Waterfall, because everything else changes). > Tosh. http://www.agilemodeling.com/essays/agileModelingXP.htm#Documentation "Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference." Ohhh wait, you mean that internal documentation is a waste of time, not customer facing (and requested) documentation. Right? That'll be why, as one of three technical authors working within an XP driven development team (and I mean within as in sitting alongside, contributing to design discussions, arguing UI points, trying early builds) we are struggling to keep up with the (external) documentation requirements. Gordon This email (and any attachments) is private and confidential, and is intended solely for the addressee. If you have received this communication in error please remove it and inform us via telephone or email. Although we take all possible steps to ensure mail and attachments are free from malicious content, malware and viruses, we cannot accept any responsibility whatsoever for any changes to content outwith our administrative bounds. The views represented within this mail are solely the view of the author and do not reflect the views of the organisation as a whole. Graham Technology plc Registered in Scotland company no. SC143434 Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH http://www.grahamtechnology.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/john%40hedtke.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Sorry for the bandwidth, but is the Frameusers site functioning?
Van Boening, Tammy wrote: > I have been trying in vain to unsubscribe from the framers > list and tech-whirl list for several days now as I am leaving > this gig and will soon have a new email address; however, no > luck. No matter what I do, whenever I log in, I either get > timed out or when I try to unsubscribe, an access denied > message. I even tried sending an email direct to the > listadmin email address that is listed on the first page of > the website, but I get immediate bounce back from that as > undeliverable. Has anyone else been experiencing these or > similar problems with the site? Did you try both the methods listed at the bottom of each list message? "To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit [a lists.frameusers.com address personalized for you]" When I click my personalized link in the above message, it takes me directly to my "member options" page, which has login, unsubscribe, and password reminder buttons. Since the unsubscribe involves responding to a confirmation message, sending an blank email (from the subscribed address, of course) would seem to be the simpler process. :-) Richard -- Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 --
Re: footnote problem
Bodvar Bjorgvinsson wrote: My walnut is telling me that a footnote is a footnote and things that do not fit within the majority of a page as allowed in FrameMaker must be something else, like an end note or just as an "insert" (not in the FM way) that is just shown indented and/or in smaller type in direct continuation of the subject section/part/paragraph. ...and if you checked it, you'd find the Chicago Manual of Style telling you pretty much the same thing. Tina, you might want to have a look through section 15 of CMOS, especially "Extensive versus Excessive Documentation" beginning at 15.15 and Footnotes beginning at 15.41. (14th Edition; the 15th ed. on line puts this info in section 16.) These sections contain a good description of the problem your author is creating, in terms of book layout and typesetting (i.e., not particular to FM or any other software) and cogent arguments that you might deliver to him suggesting a different approach. There are also suggestions on how to reduce the size of long footnotes if there is simply no way to avoid them. HTH, -- Stuart Rogers Technical Communicator Phoenix Geophysics Limited Toronto, ON, Canada +1 (416) 491-7340 x 325 srogers phoenix-geophysics com "On the contrary." -- Henrik Ibsen (last words, after a nurse said he "seemed a little better.") ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
> > The movement toward Extreme Programming and Agile Development is a > case in point; documentation is considered a waste of valuable > developer time, and only needs to be slapped together in minimalist > form at the last minute. That is at odds with the "TW perspective" > of involvement during the entire development process (which is ONLY > appropriate for Waterfall, because everything else changes). > Tosh. http://www.agilemodeling.com/essays/agileModelingXP.htm#Documentation "Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference." Ohhh wait, you mean that internal documentation is a waste of time, not customer facing (and requested) documentation. Right? That'll be why, as one of three technical authors working within an XP driven development team (and I mean within as in sitting alongside, contributing to design discussions, arguing UI points, trying early builds) we are struggling to keep up with the (external) documentation requirements. Gordon This email (and any attachments) is private and confidential, and is intended solely for the addressee. If you have received this communication in error please remove it and inform us via telephone or email. Although we take all possible steps to ensure mail and attachments are free from malicious content, malware and viruses, we cannot accept any responsibility whatsoever for any changes to content outwith our administrative bounds. The views represented within this mail are solely the view of the author and do not reflect the views of the organisation as a whole. Graham Technology plc Registered in Scotland company no. SC143434 Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH http://www.grahamtechnology.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
Agreed. I'm surprised this isn't a more common practice. On 10/18/07, Chris Borokowski <[EMAIL PROTECTED]> wrote: > What makes more sense in my mind is for technical writers to expand > their role to the life-cycle of the product, from conception to > maintenance, by investing in understanding interaction design/interface > design, quality control and user advocacy positions. -- Bill Swallow HATT List Owner WWP-Users List Owner Senior Member STC, TechValley Chapter STC Single-Sourcing SIG Manager http://techcommdood.blogspot.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: Sorry for the bandwidth, but is the Frameusers site functioning?
Van Boening, Tammy wrote: > I have been trying in vain to unsubscribe from the framers > list and tech-whirl list for several days now as I am leaving > this gig and will soon have a new email address; however, no > luck. No matter what I do, whenever I log in, I either get > timed out or when I try to unsubscribe, an access denied > message. I even tried sending an email direct to the > listadmin email address that is listed on the first page of > the website, but I get immediate bounce back from that as > undeliverable. Has anyone else been experiencing these or > similar problems with the site? Did you try both the methods listed at the bottom of each list message? "To unsubscribe send a blank email to [EMAIL PROTECTED] or visit [a lists.frameusers.com address personalized for you]" When I click my personalized link in the above message, it takes me directly to my "member options" page, which has login, unsubscribe, and password reminder buttons. Since the unsubscribe involves responding to a confirmation message, sending an blank email (from the subscribed address, of course) would seem to be the simpler process. :-) Richard -- Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 -- ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
radical revamping of techpubs
A pithy and very well-written message, Ron. Bravo! Yours truly, John Hedtke Author/Consultant/Contract Writer www.hedtke.com <-- website 541-685-5000 (office landline) 541-554-2189 (cell) john at hedtke.com (primary email) johnhedtke at aol.com (secondary email)
Re: radical revamping of techpubs
A pithy and very well-written message, Ron. Bravo! Yours truly, John Hedtke Author/Consultant/Contract Writer www.hedtke.com <-- website 541-685-5000 (office landline) 541-554-2189 (cell) [EMAIL PROTECTED] (primary email) [EMAIL PROTECTED] (secondary email) ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
What makes more sense in my mind is for technical writers to expand their role to the life-cycle of the product, from conception to maintenance, by investing in understanding interaction design/interface design, quality control and user advocacy positions. --- Ron Miller <[EMAIL PROTECTED]> wrote: > > > > > On Oct 11, 2007, at 10:23 AM, Technical Writer wrote: > > > > > The trend has been in that direction since the dotcom bust, when a > > > number of (formerly) highly paid developers found a comfortable job > > > writing help files more appealing than unemployment or stocking the > > > shelves at Wal-Mart. > > If they have writing skills, then they can make a living as a tech > writer, and more power to them, but just because they are technical > certainly doesn't mean they can write. > > > > > > While it is easy for technical writers to convince themselves of > > the value of what they do, the simple truth is that many users lack > > > the linguistic and cognitive sophistication to distinguish between > > > "good" writing and "mediocre" writing. > > > I'm sorry, but that's just a gross generalization and there's no way > > you could realistically back up the statement. > > > > > > > Similarly, it is easy for technical writers to believe they are > > documenting the software, when in fact they are only documenting > > the interface. The trend in development is to make the interface > > more intuitive, hence easier to use; if the interface requires > > extensive documentation about how to use it, it is a failure of > > design, not of documentation. That follows the way the overwhelming > > > majority of users actually interact with software--they start it > > up, click a few buttons, and generally try to figure out how it > > works. For a well-designed user interface, that should be enough to > > > get started. > > Should be, but for the majority of users in the world, it's not that > > simple. My experience is that you are making a huge mistake if you > assume your users have the same level of computer aptitude that you > and your colleagues have. Of course, it all depends on audience, but > > in a typical commercial software program, I believe you have to > document to the lowest common denominator and that means assuming > little or no computer skills. If you want proof of this, look not > further than Office 2007 with its radical interface redesign. In > theory, that means it should be easier to use, but in practice, you > have to learn where all the tools are after years of doing it another > > way. Without good training and documentation, the average user who > has been using Word with a menu bar/toolbar metaphor for umpteen > years is going to have a very rough go trying to find his/her way > around. Heck, I'm an experienced user and I find it maddening. > > > > > > The movement toward Extreme Programming and Agile Development is a > > > case in point; documentation is considered a waste of valuable > > developer time, and only needs to be slapped together in minimalist > > > form at the last minute. That is at odds with the "TW perspective" > > > of involvement during the entire development process (which is ONLY > > > appropriate for Waterfall, because everything else changes). > > > > > > I can't speak to this because I don't delve into programming and > development theory, but I can say that as a tech writer with 20 years > > experience, that one of my big value adds is acting as the voice of > the end user. Developing involves a series of choices often made in > haste, and often involving a number of people working separately on > different pieces. I've found that as a person looking at the entire > program, and carefully documenting how it works, I can act not only > as another QA piece, but also recognize inconsistencies and bad > choices and I can make suggestions for improving the program. If you > > bring me in at the end of the process, there is less time to react to > > these types of changes. If I'm involved from the beginning, I can act > > as another set of eyes. > > > > Because there is already a dichotomy between the GUI developers and > > > the "real" programmers, it is a small step to realize that the best > > > people to provide the minimalist documentation necessary to use the > > > interface are the developers of that interface. If the interface > > requires more than minimalist documentation, the core problem is > > the failure of the design, not a lack of technical writers. > > Minimalist documentation should be based on the remarks (in the > > code) of the developers, not a secondary understanding of a > > technical writer acting as a third party. > > Yea, in theory, maybe, but in reality, you can't know if the GUI is > dead easy to use, because you can't possibly assume you know the > computer aptitude of your entire customer base. In my ex
radical revamping of techpubs
What makes more sense in my mind is for technical writers to expand their role to the life-cycle of the product, from conception to maintenance, by investing in understanding interaction design/interface design, quality control and user advocacy positions. --- Ron Miller wrote: > > > > > On Oct 11, 2007, at 10:23 AM, Technical Writer wrote: > > > > > The trend has been in that direction since the dotcom bust, when a > > > number of (formerly) highly paid developers found a comfortable job > > > writing help files more appealing than unemployment or stocking the > > > shelves at Wal-Mart. > > If they have writing skills, then they can make a living as a tech > writer, and more power to them, but just because they are technical > certainly doesn't mean they can write. > > > > > > While it is easy for technical writers to convince themselves of > > the value of what they do, the simple truth is that many users lack > > > the linguistic and cognitive sophistication to distinguish between > > > "good" writing and "mediocre" writing. > > > I'm sorry, but that's just a gross generalization and there's no way > > you could realistically back up the statement. > > > > > > > Similarly, it is easy for technical writers to believe they are > > documenting the software, when in fact they are only documenting > > the interface. The trend in development is to make the interface > > more intuitive, hence easier to use; if the interface requires > > extensive documentation about how to use it, it is a failure of > > design, not of documentation. That follows the way the overwhelming > > > majority of users actually interact with software--they start it > > up, click a few buttons, and generally try to figure out how it > > works. For a well-designed user interface, that should be enough to > > > get started. > > Should be, but for the majority of users in the world, it's not that > > simple. My experience is that you are making a huge mistake if you > assume your users have the same level of computer aptitude that you > and your colleagues have. Of course, it all depends on audience, but > > in a typical commercial software program, I believe you have to > document to the lowest common denominator and that means assuming > little or no computer skills. If you want proof of this, look not > further than Office 2007 with its radical interface redesign. In > theory, that means it should be easier to use, but in practice, you > have to learn where all the tools are after years of doing it another > > way. Without good training and documentation, the average user who > has been using Word with a menu bar/toolbar metaphor for umpteen > years is going to have a very rough go trying to find his/her way > around. Heck, I'm an experienced user and I find it maddening. > > > > > > The movement toward Extreme Programming and Agile Development is a > > > case in point; documentation is considered a waste of valuable > > developer time, and only needs to be slapped together in minimalist > > > form at the last minute. That is at odds with the "TW perspective" > > > of involvement during the entire development process (which is ONLY > > > appropriate for Waterfall, because everything else changes). > > > > > > I can't speak to this because I don't delve into programming and > development theory, but I can say that as a tech writer with 20 years > > experience, that one of my big value adds is acting as the voice of > the end user. Developing involves a series of choices often made in > haste, and often involving a number of people working separately on > different pieces. I've found that as a person looking at the entire > program, and carefully documenting how it works, I can act not only > as another QA piece, but also recognize inconsistencies and bad > choices and I can make suggestions for improving the program. If you > > bring me in at the end of the process, there is less time to react to > > these types of changes. If I'm involved from the beginning, I can act > > as another set of eyes. > > > > Because there is already a dichotomy between the GUI developers and > > > the "real" programmers, it is a small step to realize that the best > > > people to provide the minimalist documentation necessary to use the > > > interface are the developers of that interface. If the interface > > requires more than minimalist documentation, the core problem is > > the failure of the design, not a lack of technical writers. > > Minimalist documentation should be based on the remarks (in the > > code) of the developers, not a secondary understanding of a > > technical writer acting as a third party. > > Yea, in theory, maybe, but in reality, you can't know if the GUI is > dead easy to use, because you can't possibly assume you know the > computer aptitude of your entire customer base. In my experience, > peopl
Re: radical revamping of techpubs
On Oct 11, 2007, at 10:23 AM, Technical Writer wrote: The trend has been in that direction since the dotcom bust, when a number of (formerly) highly paid developers found a comfortable job writing help files more appealing than unemployment or stocking the shelves at Wal-Mart. If they have writing skills, then they can make a living as a tech writer, and more power to them, but just because they are technical certainly doesn't mean they can write. While it is easy for technical writers to convince themselves of the value of what they do, the simple truth is that many users lack the linguistic and cognitive sophistication to distinguish between "good" writing and "mediocre" writing. I'm sorry, but that's just a gross generalization and there's no way you could realistically back up the statement. Similarly, it is easy for technical writers to believe they are documenting the software, when in fact they are only documenting the interface. The trend in development is to make the interface more intuitive, hence easier to use; if the interface requires extensive documentation about how to use it, it is a failure of design, not of documentation. That follows the way the overwhelming majority of users actually interact with software--they start it up, click a few buttons, and generally try to figure out how it works. For a well-designed user interface, that should be enough to get started. Should be, but for the majority of users in the world, it's not that simple. My experience is that you are making a huge mistake if you assume your users have the same level of computer aptitude that you and your colleagues have. Of course, it all depends on audience, but in a typical commercial software program, I believe you have to document to the lowest common denominator and that means assuming little or no computer skills. If you want proof of this, look not further than Office 2007 with its radical interface redesign. In theory, that means it should be easier to use, but in practice, you have to learn where all the tools are after years of doing it another way. Without good training and documentation, the average user who has been using Word with a menu bar/toolbar metaphor for umpteen years is going to have a very rough go trying to find his/her way around. Heck, I'm an experienced user and I find it maddening. The movement toward Extreme Programming and Agile Development is a case in point; documentation is considered a waste of valuable developer time, and only needs to be slapped together in minimalist form at the last minute. That is at odds with the "TW perspective" of involvement during the entire development process (which is ONLY appropriate for Waterfall, because everything else changes). I can't speak to this because I don't delve into programming and development theory, but I can say that as a tech writer with 20 years experience, that one of my big value adds is acting as the voice of the end user. Developing involves a series of choices often made in haste, and often involving a number of people working separately on different pieces. I've found that as a person looking at the entire program, and carefully documenting how it works, I can act not only as another QA piece, but also recognize inconsistencies and bad choices and I can make suggestions for improving the program. If you bring me in at the end of the process, there is less time to react to these types of changes. If I'm involved from the beginning, I can act as another set of eyes. Because there is already a dichotomy between the GUI developers and the "real" programmers, it is a small step to realize that the best people to provide the minimalist documentation necessary to use the interface are the developers of that interface. If the interface requires more than minimalist documentation, the core problem is the failure of the design, not a lack of technical writers. Minimalist documentation should be based on the remarks (in the code) of the developers, not a secondary understanding of a technical writer acting as a third party. Yea, in theory, maybe, but in reality, you can't know if the GUI is dead easy to use, because you can't possibly assume you know the computer aptitude of your entire customer base. In my experience, people have very little computer savvy and mostly know only how to use the bundle of programs they use regularly. If you take them outside of that comfort zone, it's like starting from scratch. If a technical writer wants to document software, he or she should learn to program competently. Similarly, a GUI developer who wants to stay employed should learn the basic skill set needed to convert remarks in the code to help files. The dichotomy between developer and writer is artificial, and not particularly useful. Developers don't need a Master's in Englis
Creating context sensitive help for applications built using DOT NET studio.
Hi all, Have any of you created .chm files for applications built using the .NET studio? The problem that interests me is the lack of a ui.h file for the context mapping. .NET no longer uses this MFC convention. For the same reason, Microsoft help studio cannot trap HTML help messages for these applications. Any interesting links would be appreciated. Thanks, Paul ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Convert PDF to DOC or FM
Can't you just use Acrobat Professional 8? It translates the PDF to Word as text insets, which you then change to pure text. It works for me. Joel On 10/17/07 11:59 AM, "O'Laoghaire Micheal" wrote: > Try using Nuance's PDFConverter4 ( http://www.nuance.com/pdfconverter/) for > converting PDF to MS Word. > > It's not perfect, but it does a reasonably good job. > > Faults > Internal xrefs and hypertext links usually get broken. > Sometimes, some graphics get dropped as well. > > > Regards, > Micheal O'Laoghaire > CBS Documentation > Comverse Inc. > Cambridge, MA. > > Tel: (617) 273-5414 > > -Original Message- > From: framers-bounces+micheal.olaoghaire=comverse.com at lists.frameusers.com > [mailto:framers-bounces+micheal.olaoghaire=comverse.com at > lists.frameusers.com] > On Behalf Of Caroline Tabach > Sent: Wednesday, October 17, 2007 5:39 AM > To: framers at lists.frameusers.com > Subject: Convert PDF to DOC or FM > > Hi, > The question is, where did the PDF come from. > For instance, in some PDF files created where I work, the text is actually > exported from a graphics program as a graphic, and therefore it cannot be > easily turned into Word or Frame. In other words, are you sure that the text > in the PDF is really text? > __> _ > > Message: 2 > Date: Tue, 16 Oct 2007 09:34:45 -0500 > From: Doug > Subject: Convert PDF to DOC or FM > To: undisclosed-recipients:; > Message-ID: ><5b7f194e0710160734q16727449v203422ee07055dd3 at mail.gmail.com> > Content-Type: text/plain; charset=ISO-8859-1 > > Hiya folks, > > I have a PDF file that I want to edit using either FrameMaker or Word. > However, when I use Acrobat 7 to save it as either DOC or RTF, the only thing > that gets saved are the headings. At first I thought it was the bookmarks > that were being saved, but the same thing happened after I deleted the > bookmarks and then resaved it. > > Any ideas on what's going on, or why this is happening? No security has been > implemented in the PDF. > > I can save the file as PS or EPS and it seems large enough to be the full > document, not just the six or so pages of bookmarks/headings, but I don't know > how to convert PS or EPS to FM or DOC. Ideas? > > Thanks! > > --Doug > __ > > Caroline Tabach > Technical/Marcom Writer > > > > Fax: +972 3 6474681 > Email: caroline at radcom.com > www.radcom.com > www.protocols.com > > > ___ > > > You are currently subscribed to Framers as Micheal.OLaoghaire at comverse.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/micheal.olaoghaire%40comve > rse.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 eleysium 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/eleysium%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info.
RE: Boolean condition expression problems in FM 8
Hi, Sorry, 2 more issues: o I noticed that boolean expressions set in one file of a book are not overridden when I set "Show All" for the whole book. In this file still "Show as per Expression" is set. o When I want to set boolean expressions for the whole book, not all available conditions are shown in the boolean expression window. In the "Show/Hide Conditional Text" all conditions are shown correctly. Best regards Winfried > We have a "comment" condition which should be hidden in the > final document and other conditions which should be shown. > However, here I ran into problems, when I have text which > has "comment" and another condition applied, and text with > "comment" should be hidden. I tried this: > > o "draft"OR"print"OR"nursecall"ORNOT"comment" -> Text which > has "nursecall" and "comment" assigned is shown. > > o "nurse call"ANDNOT"comment"OR"draft"OR"print" -> Text which > has "nursecall" and "comment" assigned is hidden. That's > exactly what I want and it works. Very good. However I cannot > explain why. Obviously the order is important. But I do not > want to try all possibilities. > In my oppinion I would need the option to group the single > elements in this expression. But that's not allowed. > > > > And other condition issues: > > o I have to close all condition windows when I want to do > something else. I cannot leave them open as before. > > o When I select "Show All" and "Set" and then again an expression > my latest expression got lost. > > o The FM documentation is not correct when it says: 5. Click > the AND, OR, or NOT button. > When I need "NOT" the result must be ANDNOT or ORNOT. > I miss examples. > > And another minor annoyance: When in FM e.g. the paragraph > designer was active and I switch to another application and go > back to FM, FM 8 displays now only the paragraph designer. The > whole FM window should be shown. > > Best regards > > Winfried ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: footnote problem
My walnut is telling me that a footnote is a footnote and things that do not fit within the majority of a page as allowed in FrameMaker must be something else, like an end note or just as an "insert" (not in the FM way) that is just shown indented and/or in smaller type in direct continuation of the subject section/part/paragraph. I understand the problem, although I have not had to deal with it (other than when the footnote reference is too low on the page for the footnote itself to fit). This problem has come up several times on the list IIRC. I have no other solution than this and, then maybe to cross-reference it. Is this something that can be overridden by a FrameScript? I guess not. Adobe should look into this along with some other quirks, like the feathering problem when you have an anchored frame on a page, and/or balanced columns. Bodvar On 10/18/07, Graeme R Forbes <[EMAIL PROTECTED]> wrote: > Tina wrote: > > "If I take out > the now disappeared long footnote (by deleting the footnote reference in the > text), all the other footnotes go back where they belong" > > Are you sure about this? If there are lots of long notes in the doc > it's very likely that FM has pushed some of them in their entirety > onto the following page. FrameMaker can't split long notes across > pages correctly. Useless behavior which, as Rick said, has been with > us since FM 4 (FM 3 in my experience, and no doubt since FM 1 -- the > footnote facility was programmed to do exactly what it does, by > people who didn't understand how footnotes are supposed to behave). > So you have to break them manually, using text boxes inside anchored > frames for the part of the note that won't fit on the page with the > reference number in the main text. Or else make them all endnotes by > the ugly method described in the user manual, which I once automated > in Applescript. But endnotes are so reader-hostile that it's worth > slogging thro' the manual process. > > Graeme Forbes > ___ > > > You are currently subscribed to Framers as [EMAIL PROTECTED] > > Send list messages to [EMAIL PROTECTED] > > To unsubscribe send a blank email to > [EMAIL PROTECTED] > or visit > http://lists.frameusers.com/mailman/options/framers/bodvar%40gmail.com > > Send administrative questions to [EMAIL PROTECTED] Visit > http://www.frameusers.com/ for more resources and info. > ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Boolean condition expression problems in FM 8
Hi, We have a "comment" condition which should be hidden in the final document and other conditions which should be shown. However, here I ran into problems, when I have text which has "comment" and another condition applied, and text with "comment" should be hidden. I tried this: o "draft"OR"print"OR"nursecall"ORNOT"comment" -> Text which has "nursecall" and "comment" assigned is shown. o "nurse call"ANDNOT"comment"OR"draft"OR"print" -> Text which has "nursecall" and "comment" assigned is hidden. That's exactly what I want and it works. Very good. However I cannot explain why. Obviously the order is important. But I do not want to try all possibilities. In my oppinion I would need the option to group the single elements in this expression. But that's not allowed. And other condition issues: o I have to close all condition windows when I want to do something else. I cannot leave them open as before. o When I select "Show All" and "Set" and then again an expression my latest expression got lost. o The FM documentation is not correct when it says: 5. Click the AND, OR, or NOT button. When I need "NOT" the result must be ANDNOT or ORNOT. I miss examples. And another minor annoyance: When in FM e.g. the paragraph designer was active and I switch to another application and go back to FM, FM 8 displays now only the paragraph designer. The whole FM window should be shown. Best regards Winfried ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: Footnote problem--long footnotes
On 17 Oct 2007 at 12:59, Tina Ricks wrote: > Has anyone seen this? Any ideas about how to deal with long footnotes in > Frame other than go back to the author and tell him to rewrite? Well, I think the author will insist... So I would try a quirk, because the whole text seems to be a quirk anyhow: - Put the text of the extra long footnote aside - At the page place only an introductory part of this long footnote with a cross reference to the full text: 127)Hecate est Iovis et Latonae filia, soror Apollinis. Est tricopor et triceps, magicarum artium magistra ac fascinationum praeses, cinctra latrantium canum turma. (see complete footnote at page 312). - Place this awful footnote in an appendix, where you probably have other strange things also. Klaus Daube Docu + Design Daube; Schäracher 11; CH-8053 Zürich Technical documentation & consultancy; On-line and paper Phone: +41-44-422 86 25 FAX: +41-44-422 82 78 E-mail: [EMAIL PROTECTED] Web: www.daube.ch/ ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
footnote problem
Tina wrote: "If I take out the now disappeared long footnote (by deleting the footnote reference in the text), all the other footnotes go back where they belong" Are you sure about this? If there are lots of long notes in the doc it's very likely that FM has pushed some of them in their entirety onto the following page. FrameMaker can't split long notes across pages correctly. Useless behavior which, as Rick said, has been with us since FM 4 (FM 3 in my experience, and no doubt since FM 1 -- the footnote facility was programmed to do exactly what it does, by people who didn't understand how footnotes are supposed to behave). So you have to break them manually, using text boxes inside anchored frames for the part of the note that won't fit on the page with the reference number in the main text. Or else make them all endnotes by the ugly method described in the user manual, which I once automated in Applescript. But endnotes are so reader-hostile that it's worth slogging thro' the manual process. Graeme Forbes
Re: footnote problem
Tina wrote: "If I take out the now disappeared long footnote (by deleting the footnote reference in the text), all the other footnotes go back where they belong" Are you sure about this? If there are lots of long notes in the doc it's very likely that FM has pushed some of them in their entirety onto the following page. FrameMaker can't split long notes across pages correctly. Useless behavior which, as Rick said, has been with us since FM 4 (FM 3 in my experience, and no doubt since FM 1 -- the footnote facility was programmed to do exactly what it does, by people who didn't understand how footnotes are supposed to behave). So you have to break them manually, using text boxes inside anchored frames for the part of the note that won't fit on the page with the reference number in the main text. Or else make them all endnotes by the ugly method described in the user manual, which I once automated in Applescript. But endnotes are so reader-hostile that it's worth slogging thro' the manual process. Graeme Forbes ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
