RE: radical revamping of techpubs
There's also a heckuva lot more to editing than just a grammar check by a bunch of kids (or any grammar-checker, for that matter). Rene Stephenson "Denise L. Moss-Fritch" <[EMAIL PROTECTED]> wrote: Good Day Mulholland, Sorry, in my opinion the plan is not in the best interest of the customers. There is far more to "writing documentation" than knowing the application being developed. Will the documentation be print (or Acrobat files), or online help? Each format has a different structure and requires a different form of authoring. While print (or Acrobat) form follows a book format of typically related information that includes transitions between paragraphs, sections, and chapters; online help follows a different (individual topic) format. Typically online help topics follow a pattern of overview, drilling down to specific topics that further explain, describe the interface and option, and offer specific procedures. However, such a process does not describe higher level processes that might include several options (dialogs or tabs). If you really must follow such a process because of costs (although typically tech writers are paid half of what developers earn), remember you will be taking development time from your staff. I would also recommend an initial development edit that would review the structure and basic types of content of your documentation. The second edit would focus upon language. Best, Denise L. Moss-Fritch -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of mulholland4 Sent: Wednesday, October 10, 2007 12:55 PM To: framers@lists.frameusers.com Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/d.mossfritch%40comcast.n et 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/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.
Re: radical revamping of techpubs
On a personal basis, it'd mean that if anyone in management was even floating the idea, that it's past time to rev your resume because the company ain't going to be around long. ;- ) Art On 10/10/07, mulholland4 <[EMAIL PROTECTED]> wrote: > Hi, > I would like to see what the group thinks of this scenario for writing > documentation within a company? > > 1. Remove all existing tech writing staff from techpubs. > 2. Replace these with software developers and specialists who know the > software inside out and get them to write all of the documentation. These > would now be known as Developer-techwriters. (It should be noted that none > of these people has English as a first language, despite this being the > primary market for the documentation.) > 3. Hire editing staff to edit only the language and grammar of the documents > written by the software specialists. > > The reasoning behind this scenario is; that this saves money as the > developers know the software, and it is really cheap to get university > students to come in and edit. > > I won't make comments on this just now as i'm sure there are many of us who > just want to run screaming! > > thanks > Mulholland > ___ > > -- Art Campbell [EMAIL PROTECTED] "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson No disclaimers apply. DoD 358 ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
Yep, they would: extra money in the corporate pockets to show for the lower quality to the customers and resultant increase in customer calls for tech support. You get what you pay for...a short-term gain. Rene Steve Rickaby <[EMAIL PROTECTED]> wrote: At 15:54 -0400 10/10/07, mulholland4 wrote: >I would like to see what the group thinks of this scenario for writing >documentation within a company? Off-hand I would hazard a guess that any company trying this would reap the rewards quite quickly. -- Steve ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/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.
RE: radical revamping of techpubs
Good Day Mulholland, Sorry, in my opinion the plan is not in the best interest of the customers. There is far more to "writing documentation" than knowing the application being developed. Will the documentation be print (or Acrobat files), or online help? Each format has a different structure and requires a different form of authoring. While print (or Acrobat) form follows a book format of typically related information that includes transitions between paragraphs, sections, and chapters; online help follows a different (individual topic) format. Typically online help topics follow a pattern of overview, drilling down to specific topics that further explain, describe the interface and option, and offer specific procedures. However, such a process does not describe higher level processes that might include several options (dialogs or tabs). If you really must follow such a process because of costs (although typically tech writers are paid half of what developers earn), remember you will be taking development time from your staff. I would also recommend an initial development edit that would review the structure and basic types of content of your documentation. The second edit would focus upon language. Best, Denise L. Moss-Fritch -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of mulholland4 Sent: Wednesday, October 10, 2007 12:55 PM To: framers@lists.frameusers.com Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/d.mossfritch%40comcast.n et Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
In my opinion, the developer is the most ill-suited person to be writing the documentation. Their knowledge of the product is frequently too deep for the average user and the end result is often woefully inadequate for said average user. The fact that the developers are not native-English speakers merely adds insult to injury. Was this some pencil-pusher's idea of a cost cutting measure? Did he factor in the cost of all the additional phone support that will now be required? Or is your firm one of those that charges from the first minute for any support? Berny Gagne Lead Writer Husky Injection Molding Systems Ltd. Bolton, Ontario, Canada -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of mulholland4 Sent: Wednesday, October 10, 2007 3:55 PM To: framers@lists.frameusers.com Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/bgagne%40husky.ca Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
Sounds like a recipe for disaster to me -- at least as far as the customer is concerned. Although the company might enjoy a short-term savings, they'll pay for it in the longer term in increased support costs (unless they off-shore that too) and customer dissatisfaction. ...Susan - Original Message From: mulholland4 <[EMAIL PROTECTED]> To: framers@lists.frameusers.com Sent: Wednesday, October 10, 2007 12:54:37 PM Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/smodlin%40yahoo.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. Pinpoint customers who are looking for what you sell. http://searchmarketing.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.
Re: radical revamping of techpubs
My prediction is that it will be a partial disaster, and then they'll hire a contractor to come clean up. Few companies are interested in keeping technical writers around full time, since they're only needed at the end of the design process. They want dual roles, such as project manager technical writers, developer technical writers and probably even technical writers who can cook to reduce catering costs. --- Susan Modlin <[EMAIL PROTECTED]> wrote: > Sounds like a recipe for disaster to me -- at least as far as the > customer is concerned. Although the company might enjoy a short-term > savings, they'll pay for it in the longer term in increased support > costs (unless they off-shore that too) and customer dissatisfaction. > > ...Susan > > - Original Message > From: mulholland4 <[EMAIL PROTECTED]> > To: framers@lists.frameusers.com > Sent: Wednesday, October 10, 2007 12:54:37 PM > Subject: radical revamping of techpubs > > > Hi, > I would like to see what the group thinks of this scenario for > writing > documentation within a company? > > 1. Remove all existing tech writing staff from techpubs. > 2. Replace these with software developers and specialists who know > the > software inside out and get them to write all of the documentation. > These > would now be known as Developer-techwriters. (It should be noted that > none > of these people has English as a first language, despite this being > the > primary market for the documentation.) > 3. Hire editing staff to edit only the language and grammar of the > documents > written by the software specialists. > > The reasoning behind this scenario is; that this saves money as the > developers know the software, and it is really cheap to get > university > students to come in and edit. > > I won't make comments on this just now as i'm sure there are many of > us > who > just want to run screaming! > > thanks > Mulholland > ___ > > > 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/smodlin%40yahoo.com > > Send administrative questions to [EMAIL PROTECTED] Visit > http://www.frameusers.com/ for more resources and info. > > > > > > > > > Pinpoint customers who are looking for what you sell. > http://searchmarketing.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/athloi%40yahoo.com > > Send administrative questions to [EMAIL PROTECTED] Visit > http://www.frameusers.com/ for more resources and info. > http://technical-writing.dionysius.com/ technical writing | consulting | development Building a website is a piece of cake. Yahoo! Small Business gives you all the tools to get online. http://smallbusiness.yahoo.com/webhosting ___ 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
This will be a complete train wreck. Here's why: 1. The Developers have no idea how to organize the information 2. When they write, they are completely illiterate. In my company, the Developers write specs for me on each new feature. They are so illiterate, that I always have to go to them and interview them to figure out what the feature actually does. 3. Their knowledge is so advanced that they don't understand the end-users viewpoint I can't tell you how many times I have heard, "You don't have to explain that, they'll know how to do that." I have had to point out countless times that my audience is an end-user new on the job who knows nothing and I have to explain everything to him. You're company may be looking at this because some number cruncher thinks it will save money, but the real cost will be a severe drop in quality, which will cause you to lose customers, lose sales, lose revenue etc. etc. Thank you, Gillian Flato Technical Writer (Software) nanometrics 1550 Buckeye Dr. Milpitas, CA. 95035 408.545.6316 408.232.5911 [EMAIL PROTECTED] -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Susan Modlin Sent: Wednesday, October 10, 2007 2:42 PM To: mulholland4; framers@lists.frameusers.com Subject: Re: radical revamping of techpubs Sounds like a recipe for disaster to me -- at least as far as the customer is concerned. Although the company might enjoy a short-term savings, they'll pay for it in the longer term in increased support costs (unless they off-shore that too) and customer dissatisfaction. ...Susan - Original Message From: mulholland4 <[EMAIL PROTECTED]> To: framers@lists.frameusers.com Sent: Wednesday, October 10, 2007 12:54:37 PM Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/smodlin%40yahoo.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. Pinpoint customers who are looking for what you sell. http://searchmarketing.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/gflato%40nanometrics .com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
At 15:54 -0400 10/10/07, mulholland4 wrote: >I would like to see what the group thinks of this scenario for writing >documentation within a company? Off-hand I would hazard a guess that any company trying this would reap the rewards quite quickly. -- Steve ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
Re: radical revamping of techpubs
> 1. Remove all existing tech writing staff from techpubs. > 2. Replace these with software developers and specialists who know the > software inside out and get them to write all of the documentation. These > would now be known as Developer-techwriters. (It should be noted that none > of these people has English as a first language, despite this being the > primary market for the documentation.) > 3. Hire editing staff to edit only the language and grammar of the documents > written by the software specialists. > > The reasoning behind this scenario is; that this saves money as the > developers know the software, and it is really cheap to get university > students to come in and edit. The plan as a whole is about a buoyant as a brick, but parts have merit. Having people who know the software inside and out as writers is optimal - this is the level at which a tech writer should be functioning. Having editors clean up language and control the style to enforce consistency has merit as well, but hungry college grads are not the right people for the job either (need talented editors to do it right). In the end, your scenario will cost the company more money in the long run. I'm sure the developers won't want to be writing the docs for very long, and turnover for the editorial roles will be high. But, with the right people in the right roles, this could work. We have developers write first pass documentation for a SDK we produce, and the writers (among other roles) make the information complete and polished. Of course, the writers are also busy building sample applications and tutorials in the meantime. You need a model where everyone *can* pitch in, but one in which every role is appreciated and respected. Yours sounds like a quick means to an end (the end being a craptastic product delivery and a low morale crew). -- 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
I don't buy your "few companies" generalization. Perhaps small pre-IPO companies and the like, but I've not met an established company that didn't have a solid tech writing staff in place. On 10/10/07, Chris Borokowski <[EMAIL PROTECTED]> wrote: > My prediction is that it will be a partial disaster, and then they'll > hire a contractor to come clean up. Few companies are interested in > keeping technical writers around full time, since they're only needed > at the end of the design process. They want dual roles, such as project > manager technical writers, developer technical writers and probably > even technical writers who can cook to reduce catering costs. -- 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
In telecom in the town I'm in, it's a rare thing to find a company (even a tier 1 telco, both American-owned and Japanese-owned) with a solid tech writing staff in place. The vast majority of tech writing jobs at all levels in this town in telecom are contract only, and they're almost all subject to frequent upheaval via organizational changes. I can't say much about other industries, because I'm too narrow - I've done nothing but telecom work for over a decade. Rene Stephenson Bill Swallow <[EMAIL PROTECTED]> wrote: I don't buy your "few companies" generalization. Perhaps small pre-IPO companies and the like, but I've not met an established company that didn't have a solid tech writing staff in place. On 10/10/07, Chris Borokowski wrote: > My prediction is that it will be a partial disaster, and then they'll > hire a contractor to come clean up. Few companies are interested in > keeping technical writers around full time, since they're only needed > at the end of the design process. They want dual roles, such as project > manager technical writers, developer technical writers and probably > even technical writers who can cook to reduce catering costs. -- 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.
Re: radical revamping of techpubs
Bill Swallow wrote: > I don't buy your "few companies" generalization. Perhaps small pre-IPO > companies and the like, but I've not met an established company that > didn't have a solid tech writing staff in place. Correct ... and even small, pre-IPO, companies often have competent, professional, tech writers. :) We have 60 employees (10 in SW Engineering, 8 in HW Engineering, 15 in Network Operations, 6 in Admin/Finance and the rest in Marketing and Sales). Of the 60 employees, one is a full-time Senior Technical Writer and we also occasionally bring in technical writer contractors (1 to 3 ... depending on the needs) for crunch projects. I am not that Sr. Tech Writer, by the way, but I also produce a lot of technical material. As one of the founders, almost 75-80% of the technical docs - sent to customers - is my work ... our Sr. Tech Writer, has approved of my technical and general writing skills, fortunately! :) FWIW, I have *always* believed that quality written material for any company is fundamentally important. Otherwise, it can be a stamp of incompetence ... if a company can't provide accurate, well-written, clear, documentation, as well as a timely process of correcting errors that *do* creep in, how can customers rely on them to provide quality products and services? Regards, Z ___ 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
At the civil engineering firm where my wife has been one of the transportation engineers for almost 20 years, the story is pretty much the same. That is, the engineers are pretty proficient at road design and all that goes into it, but their reports (such as Interstate Justification Reports, or "IJR's", for instance) simply grate on me when I review a draft copy for my wife. While it's very true that this or that 30 or 40 page report -- complete with graphs, charts and maps -- will hardly be looked at, no one seems to remember the old adage, "If the job is worth doing, it's worth doing right." They figure that not even another engineer is going to look at this stuff. Probably the only things I see correctly presented within the reports are the tech specs. But the rules of grammar, punctuation and presentation simply fly out the window when these babies are assembled before I get one to look at. Luckily, the ones my wife do are each an improvement over the previous ones. The firm has no one dedicated to tech writing / tech editing on staff. I've approached the firm about reviewing their reports on a contract basis, but they're not interested -- yet. -- Ken in Atlanta -- Original message from "Flato, Gillian" <[EMAIL PROTECTED]>: -- > This will be a complete train wreck. > > Here's why: > > 1. The Developers have no idea how to organize the information > 2. When they write, they are completely illiterate. > In my company, the Developers write specs for me on each new > feature. They are so illiterate, that I always have to go to them and > interview them to figure out what the feature actually does. > 3. Their knowledge is so advanced that they don't understand the > end-users viewpoint > I can't tell you how many times I have heard, "You don't have to > explain that, they'll know how to do that." I have had to point out > countless times that my audience is an end-user new on the job who knows > nothing and I have to explain everything to him. > > You're company may be looking at this because some number cruncher > thinks it will save money, but the real cost will be a severe drop in > quality, which will cause you to lose customers, lose sales, lose > revenue etc. etc. > > > Thank you, > > > Gillian Flato > Technical Writer (Software) > nanometrics > 1550 Buckeye Dr. > Milpitas, CA. 95035 > 408.545.6316 > 408.232.5911 > [EMAIL PROTECTED] > > > -Original Message- > From: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED] On > Behalf Of Susan Modlin > Sent: Wednesday, October 10, 2007 2:42 PM > To: mulholland4; framers@lists.frameusers.com > Subject: Re: radical revamping of techpubs > > Sounds like a recipe for disaster to me -- at least as far as the > customer is concerned. Although the company might enjoy a short-term > savings, they'll pay for it in the longer term in increased support > costs (unless they off-shore that too) and customer dissatisfaction. > > ...Susan > > - Original Message > From: mulholland4 > To: framers@lists.frameusers.com > Sent: Wednesday, October 10, 2007 12:54:37 PM > Subject: radical revamping of techpubs > > > Hi, > I would like to see what the group thinks of this scenario for writing > documentation within a company? > > 1. Remove all existing tech writing staff from techpubs. > 2. Replace these with software developers and specialists who know the > software inside out and get them to write all of the documentation. > These > would now be known as Developer-techwriters. (It should be noted that > none > of these people has English as a first language, despite this being the > primary market for the documentation.) > 3. Hire editing staff to edit only the language and grammar of the > documents > written by the software specialists. > > The reasoning behind this scenario is; that this saves money as the > developers know the software, and it is really cheap to get university > students to come in and edit. > > I won't make comments on this just now as i'm sure there are many of us > who > just want to run screaming! > > thanks > Mulholland > ___ > > > 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/smodlin%40yahoo.com > > Send administrative questions to [EMAIL PROTECTED] Visit > http://www.
Re: radical revamping of techpubs
Just to throw my opinion on the fire as well, yeah, I'd say it's time to make like a tree and get outa there. :) It's the same old leftovers we've seen a zillion times before. The fact that the developers are not writers >nor< native English speakers just adds a comic twist to the incompetence of the people who made such a boneheaded decision. I'm sure that there will be a certain amount of smugness about how original they've been, but you may quote me by saying what I always say whenever I hear this kind of rank stupidity coming from some Richard Cranium type: "Aye, we've steered onto the rocks. I ~told~ you it was bad luck to steer straight onto the rocks!" Care to tell us the name of the company so we can short their stock? :) Yours truly, John Hedtke Author/Consultant/Contract Writer www.hedtke.com <-- website Region 7 Director, STC 541-685-5000 (office landline) 541-554-2189 (cell) [EMAIL PROTECTED] (primary email) [EMAIL PROTECTED] (secondary email) At 11:47 AM 10/10/2007, mulholland4 wrote: Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! ___ 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
They will get exactly what they desirve - a complete disaster. Companies that do not know the value of technical documentation, user documentation, in what ever form it is needed will lose business and market share, in the same way that companies that move their customer service call centers off shore lose business because of customer dissatisfaction with that quality of support. Technical documentation is something that many managers or owners of business think they can cut corners and save money on, but very often that leads to lower quality and lower levels of customer satisfaction. And software enginers have a great set os skills to offer, but technical wirting usually isn't one of them they know the software innards but that does not mean they know how to create a user document. And you suggested that English was a second language for them; when the users get that ESL document, they are not going to be happy, and likey the first thing they will think is that they probably made a mistake to purchase that product at all; presuming they had a choice -since so much of US industry has been moved off shore. So people don't have much of a choice now, but that does not mean they are happy about it. I know I'm not. So obviously this was a very loaded question, I would think most technical writers based in a market would have the same conclusions I do about the scenario. - Original Message From: mulholland4 <[EMAIL PROTECTED]> To: framers@lists.frameusers.com Sent: Wednesday, October 10, 2007 2:54:37 PM Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/lhs_emf%40pacbell.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.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
One word answer: Bad. Unless they don't care if they have unreadable, unusable, documentation. Miriam - Original Message - From: "mulholland4" <[EMAIL PROTECTED]> To: Sent: Wednesday, October 10, 2007 3:54 PM Subject: radical revamping of techpubs Hi, I would like to see what the group thinks of this scenario for writing documentation within a company? 1. Remove all existing tech writing staff from techpubs. 2. Replace these with software developers and specialists who know the software inside out and get them to write all of the documentation. These would now be known as Developer-techwriters. (It should be noted that none of these people has English as a first language, despite this being the primary market for the documentation.) 3. Hire editing staff to edit only the language and grammar of the documents written by the software specialists. The reasoning behind this scenario is; that this saves money as the developers know the software, and it is really cheap to get university students to come in and edit. I won't make comments on this just now as i'm sure there are many of us who just want to run screaming! thanks Mulholland ___ 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/mlezak%40marzak.org Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
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. 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. 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. 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). 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. 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 English to write competent documentation, and technical writers don't need a BS in Computer Science to develop a competent interface. When the employers realize that, technical writing--as far as software documentation is concerned--is liable to become the 2008 equivalent of buggy whip manufacturing when automobiles chased the horse-drawn buggies off the road. The argument that documentation would erode developer time better spent elsewhere is spurious; the process is becoming, 1) release the software with a minimalist set of docs, then, 2) build an online help file based on the highest volume of calls to support. The concept may be uncomfortable for technical writers, but it is a concept used widely in business; "the squeaky wheel gets the grease." tekwrytr http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites _ Windows Live Hotmail and Microsoft Office Outlook – together at last. Get it now. http://office.microsoft.com/en-us/outlook/HA102225181033.aspx?pid=CL100626971033___ 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
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
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
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: 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
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
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.
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.
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.
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
> 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.
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.
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.
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.
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
Most projects have some of this tendency as well, because very few products are based on completely known technology in both functional design and interaction design. Changes occur. Clients also demand changes sometimes randomly. In my experience, the average software company calls the TW when the product is nearing completion, with completion usually meaning "five minutes before the ship date," and asks them to WTFM. --- Technical Writer <[EMAIL PROTECTED]> wrote: > The "external documentation" recommended for XP and agile development > is fundamentally different than the documentation model used in > old-style waterfall design. Because the application itself is built > in an iterative process, rather than being carved in stone, reacting > to feedback from the client, documentation before the last minute is > pointless. 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.
Re: radical revamping of techpubs
People buy things out of need and want. If the quality sucks, and they need it, what are they going to do? If an insulin pump eats batteries at a 20% higher rate than advertised, the quality sucks, but that doesn't mean that the product isn't needed. It's up to the company to fix the quality flaws and bring the product up to market expectation. No product is ever perfect. That's near impossible to do. But darn close is attainable. And quality is very much objective in most products given that you can collect quality metrics on the products themselves, log bugs, measure impact, etc. On 10/19/07, Technical Writer <[EMAIL PROTECTED]> wrote: > > And yet people still buy it. If they did not, issues of quality would be > irrelevant; only the "quality" items would be purchased, the "crap" would > languish on the dealer shelves, and we would be working rather than having > this discussion.http://www.tekwrytrs.com/Specializing in the Design, > Development, and Production of:Technical Documentation - Online Content - > Enterprise Websites -- 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
I can't see how quality can possibly be subjective if there's an entire occupation devoted to assuring it. Perhaps TW has only worked in environments where "quality" is merely a buzzword. On 10/19/07, Flato, Gillian <[EMAIL PROTECTED]> wrote: > I have seen enough bug reports in my time to know that quality is not > subjective. If the software generates a mile-long list of bugs reported > by customers and QA people, the software application is crap. -- 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
And yet people still buy it. If they did not, issues of quality would be irrelevant; only the "quality" items would be purchased, the "crap" would languish on the dealer shelves, and we would be working rather than having this discussion.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; framers@lists.frameusers.com I have seen enough bug reports in my time to know that quality is not subjective. If the software generates a mile-long list of bugs reported by customers and QA people, the software application is crap. Thank you, Gillian Flato Technical Writer (Software) nanometrics 1550 Buckeye Dr. Milpitas, CA. 95035 (408.545.6316 7 408.232.5911 * [EMAIL PROTECTED] From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, October 19, 2007 10:52 AMTo: Flato, Gillian; [EMAIL PROTECTED]: RE: radical revamping of techpubs The same could be said of pacemakers, missile control systems, and a host of others. That does not change the fact that in most software applications, perceptions of quality are highly subjective. Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; framers@lists.frameusers.com >>Quality is primarily a subjective opinion; >>Similarly, whether a product is crap or not is again an opinion, not an >>objective evaluation that can applied in all cases. When you work in the semi-conductor industry making high-tech instruments that are used in fabs (chip fabrication plants), quality is not subjective. If the tool stops running after a few thousand cycles or a part on the tool fails after only a few months of running, then it's objective. A part broke, the Tool shutdown, quality is crap, that's not subjective. TechWriters in my field document the software that runs on these types of tools. If you go to a fab, you'll see the type of tools I am taking about. BTW, why don't you identify who you are? You act so sanctimonious yet you hide behind a moniker. Have some cohones and tell us who you are. Thank you, Gillian Flato Technical Writer (Software) nanometrics 1550 Buckeye Dr. Milpitas, CA. 95035 (408.545.6316 7 408.232.5911 * [EMAIL PROTECTED] From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, October 19, 2007 9:37 AMTo: Flato, Gillian; [EMAIL PROTECTED]: RE: radical revamping of techpubs And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority.< From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wis
RE: radical revamping of techpubs
I have seen enough bug reports in my time to know that quality is not
subjective. If the software generates a mile-long list of bugs reported
by customers and QA people, the software application is crap.
Thank you,
<mailto:[EMAIL PROTECTED]>
Gillian Flato
Technical Writer (Software)
nanometrics
1550 Buckeye Dr.
Milpitas, CA. 95035
(408.545.6316
7 408.232.5911
* [EMAIL PROTECTED] <mailto:[EMAIL PROTECTED]> .com
mailto:[EMAIL PROTECTED]>
From: Technical Writer [mailto:[EMAIL PROTECTED]
Sent: Friday, October 19, 2007 10:52 AM
To: Flato, Gillian; framers@lists.frameusers.com
Subject: RE: radical revamping of techpubs
The same could be said of pacemakers, missile control systems,
and a host of others. That does not change the fact that in most
software applications, perceptions of quality are highly subjective.
Subject: RE: radical revamping of techpubs
Date: Fri, 19 Oct 2007 10:09:42 -0700
From: [EMAIL PROTECTED]
To: [EMAIL PROTECTED]; framers@lists.frameusers.com
>>Quality is primarily a subjective opinion;
>>Similarly, whether a product is crap or not is again
an opinion, not an objective evaluation that can applied in all cases.
When you work in the semi-conductor industry making
high-tech instruments that are used in fabs (chip fabrication plants),
quality is not subjective. If the tool stops running after a few
thousand cycles or a part on the tool fails after only a few months of
running, then it's objective. A part broke, the Tool shutdown, quality
is crap, that's not subjective.
TechWriters in my field document the software that runs
on these types of tools. If you go to a fab, you'll see the type of
tools I am taking about.
BTW, why don't you identify who you are? You act so
sanctimonious yet you hide behind a moniker. Have some cohones and tell
us who you are.
Thank you,
<mailto:[EMAIL PROTECTED]>
Gillian Flato
Technical Writer (Software)
nanometrics
1550 Buckeye Dr.
Milpitas, CA. 95035
(408.545.6316
7 408.232.5911
* [EMAIL PROTECTED] <mailto:[EMAIL PROTECTED]>
.com
From: Technical Writer
[mailto:[EMAIL PROTECTED]
Sent: Friday, October 19, 2007 9:37 AM
To: Flato, Gillian; framers@lists.frameusers.com
Subject: RE: radical revamping of techpubs
And I know of a CEO who used to either get there
first, or let the wannabes struggle over the crumbs. Name of Bill Gates.
Quality is primarily a subjective opinion;
witness the 90+% of the population of the planet using Windows, despite
the occasional Blue Screen of Death, or necessary re-booting
orre-installing required. Similarly, whether a product is crap or not is
again an opinion, not an objective evaluation that can applied in all
cases. The Debian flavor of Linux is considered "the best" by some, and
"the worst" by some. The opinions are subjective.
Everyone TW wants to believe that he or she is
producing quality documentation that creates a warm fuzzy in the user,
and makes customers-for-life of the company that produces whatever is
being documented. I simply suggest a reality check may be more useful.
If the TW is documenting software, perhaps he or
she should change fields to one with a slower pace of life (and
writing). The option is to accept the realities of the marketplace, and
how those influence and constrain the production of technical
documentation. In a world in which dynamic onlne help files are rapidly
replacing hard copy documents, it seems more useful to focus on
developing a skill set that enables high-volume production of acceptable
quality content, rather than obsessing over trivial (to most users)
details of grammar, construction, or voice.
In that direction may lie the future of TW--get
it written, get it online, and concentrate on the Pareto principle of
satisfying the needs of the major
RE: radical revamping of techpubs
Ron Miller wrote: > In my view, the only reason Windows has dominated personal > computing is because Microsoft bullied hardware company into > selling its products. I don't think this popular myth stands up to scrutiny. Microsoft's "bullying" wasn't primarily to get people to *use* Windows, it was to get them to *pay* for it. In the absence of bundling the OS with a new PC, vast numbers of people would have told the salesman, "I don't need an OS," and borrowed a friend's Windows disks/CD. The pressure to unbundle led MS to develop the current "activation" mechanism as a substitute defense against widespread piracy. Windows became dominant for two reasons, IMHO: (1) Microsoft didn't try to force people into overpriced proprietary hardware, like Apple did. (2) From Win 3.1 on, the average non-geek joe could install the OS (if necessary), install a new application, add a peripheral, etc., and be successful 90+% of the time by just following some simple instructions or a wizard. No having to make tedious edits to arcane commands in a bunch of barely documented scripts and config files. No struggling to resolve dependency problems and version conflicts. No scouring geek hangouts for the right hacked source code to make your CD drive work. Stuff just worked -- not always or perfectly, but often enough and well enough to satisfy the vast majority. A friend of mine who's an Oracle application programmer, and who's been running Linux at home exclusively for many years, recently got a new PC (sans OS). He spent a long weekend and then some installing Linux and getting everything configured and working -- and that was Ubuntu, which is supposed to be a very "friendly" Linux distro. Bash Microsoft all you like (and there surely is plenty to criticize, especially regarding security), but the Windows PC user experience is miles ahead of everything except the Mac -- which it beats on price and availability of software and peripherals. 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.
RE: radical revamping of techpubs
At 04:09 PM 10/19/2007, Technical Writer wrote: That's what makes marketing such a popular major. :) Truly! ___ 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
[EMAIL PROTECTED] wrote > Actually, no, that's not the case, Gillian; Tekwryter's emails > directly to me have been well-formatted. I think this is more an > effect of the listserve software doing something unexpected. Actually, it's a product of Microsoft's latest Windows Live e-mail client for hotmail subscribers. Replies that go directly to an individual are sent in HTML format and appear properly. But replies that are sent to the list are sent as plain text minus all the automatically inserted line breaks so that they appear as one big, unreadable block of text filled with angle brackets to indicate where new lines are supposed to start. It took me a few tries to work out a process that reproduces the original message properly, and it takes me a couple of extra minutes to do manual formatting that the brain-dead e-mail client should do automatically. Really annoying. But it is true that Tekwryter doesn't bother to work around the Windows Live shortcomings... Fred Ridder _ 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.
RE: radical revamping of techpubs
There is a difference between being "first to invent" and "first to successfully produce and/or market." The world is full of brilliant ideas that never go (and never went) anywhere. Xerox is PARC, not Park. What they developed was the concept of GUI, based on user interaction with a computer. The opposing view, that apps should be dumbed-down to the LCD, won out. A pity. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites CC: [EMAIL PROTECTED]; [EMAIL PROTECTED]: [EMAIL PROTECTED]: Re: radical revamping of techpubsDate: Fri, 19 Oct 2007 14:31:36 -0400To: [EMAIL PROTECTED] Gates, first to market? Gates has proven anything by innovative. He's the quintessential, 'let the other guys put it on the market and we'll steal it and market it better.' DOS? He bought the company? Windows? Stole the idea from Apple (who stole it from Xerox Park) Internet Explorer? Netscape was their first. The Zune? Don't make me laugh. Gates has been watching and copying for as long as I remember. 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 19, 2007, at 12:37 PM, Technical Writer wrote: And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority. < From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wisely fired him and put a new CEO at the helm.> > > -Gillian> > _ Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hotmailnews___ 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. _ 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
RE: radical revamping of techpubs
That's what makes marketing such a popular major. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Fri, 19 Oct 2007 11:23:07 -0700From: [EMAIL PROTECTED]: RE: radical revamping of techpubsTo: [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com The market is also driven by price, availability, and value (=quality for the price), but pervasive marketing and cut-throat competition can trump. ReneJohn Hedtke <[EMAIL PROTECTED]> wrote: You're making an assumption that the market is driven by quality. It is not, though that's certainly a factor. The market is driven even more by good marketing.At 10:58 AM 10/19/2007, Technical Writer wrote:>And yet people still buy it. If they did not, issues of quality >would be irrelevant; only the "quality" items would be purchased, >the "crap" would languish on the dealer shelves, and we would be >working rather than having this >discussion.http://www.tekwrytrs.com/Specializing in the Design, >Development, and Production of:Technical Documentation - Online >Content - Enterprise Websites>>>Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 >10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; >framers@lists.frameusers.com>>>>I have seen enough bug reports in my time to know that quality is >not subjective. If the software generates a mile-long list of bugs >reported by customers and QA people, the software application is crap.>>>Thank you,>>>Gillian Flato>Technical Writer (Software)>nanometrics>1550 Buckeye Dr.>Milpitas, CA. 95035>(408.545.6316>7 408.232.5911>* [EMAIL PROTECTED]>>>>>From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, >October 19, 2007 10:52 AMTo: Flato, Gillian; >[EMAIL PROTECTED]: RE: radical revamping of techpubs>The same could be said of pacemakers, missile control systems, and a >host of others. That does not change the fact that in most software >applications, perceptions of quality are highly subjective.>>>Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 >10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; >framers@lists.frameusers.com>>> >>Quality is primarily a subjective opinion;> >>Similarly, whether a product is crap or not is again an opinion, > not an objective evaluation that can applied in all cases.>>When you work in the semi-conductor industry making high-tech >instruments that are used in fabs (chip fabrication plants), quality >is not subjective. If the tool stops running after a few thousand >cycles or a part on the tool fails after only a few months of >running, then it's objective. A part broke, the Tool shutdown, >quality is crap, that's not subjective.>>TechWriters in my field document the software that runs on these >types of tools. If you go to a fab, you'll see the type of tools I >am taking about.>>BTW, why don't you identify who you are? You act so sanctimonious >yet you hide behind a moniker. Have some cohones and tell us who you are.>>>Thank you,>>>Gillian Flato>Technical Writer (Software)>nanometrics>1550 Buckeye Dr.>Milpitas, CA. 95035>(408.545.6316>7 408.232.5911>* [EMAIL PROTECTED]>>>>>From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, >October 19, 2007 9:37 AMTo: Flato, Gillian; >[EMAIL PROTECTED]: RE: radical revamping of techpubs> And I know of a CEO who used to either get there first, or let the > wannabes struggle over the crumbs. Name of Bill Gates. Quality is > primarily a subjective opinion; witness the 90+% of the population > of the planet using Windows, despite the occasional Blue Screen of > Death, or necessary re-booting orre-installing required. Similarly, > whether a product is crap or not is again an opinion, not an > objective evaluation that can applied in all cases. The Debian > flavor of Linux is considered "the best" by some, and "the worst" > by some. The opinions are subjective. Everyone TW wants to believe > that he or she is producing quality documentation that creates a > warm fuzzy in the user, and makes customers-for-life of the company > that produces whatever is being documented. I simply suggest a > reality check may be more useful. If the TW is documenting > software, perhaps he or she should change fields to one with a > slower pace of life (and writing). The option is to accept the > realities of the marketplace, and how those influence and constrain > the production of technical documentation. In a world in which > dynamic onlne help
RE: radical revamping of techpubs
One of the aspects of good Tech Writing is usability and formatting of text to make it easy to read for the end-user. Tekwryter can't even make an email readable, as you can see by his response below. I won't hold my breath that his documents are good quality. I guess the email below is a product of an Agile/XP email system. He also might consider getting someone to QA his email posts. -Gillian -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Technical Writer Sent: Friday, October 19, 2007 3:56 PM To: [EMAIL PROTECTED]; framers@lists.frameusers.com Subject: RE: radical revamping of techpubs Good point.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> Date: Fri, 19 Oct 2007 11:10:43 -0700> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> From: [EMAIL PROTECTED]> Subject: RE: radical revamping of techpubs> > You're making an assumption that the market is driven by quality. It > is not, though that's certainly a factor. The market is driven even > more by good marketing.> > At 10:58 AM 10/19/2007, Technical Writer wrote:> > >And yet people still buy it. If they did not, issues of quality > >would be irrelevant; only the "quality" items would be purchased, > >the "crap" would languish on the dealer shelves, and we would be > >working rather than having this > >discussion.http://www.tekwrytrs.com/Specializing in the Design, > >Development, and Production of:Technical Documentation - Online > >Content - Enterprise Websites> >> >> >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 > >10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; > >framers@lists.frameusers.com> >> >> >> >I have seen enough bug reports in my time to know that quality is > >not subjective. If the software generates a mile-long list of bugs > >reported by customers and QA people, the software application is crap.> >> >> >Thank you,> >> >> >Gillian Flato> >Technical Writer (Software)> >nanometrics> >1550 Buckeye Dr.> >Milpitas, CA. 95035> >(408.545.6316> >7 408.232.5911> >* [EMAIL PROTECTED]> >> >> >> >> >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, > >October 19, 2007 10:52 AMTo: Flato, Gillian; > >[EMAIL PROTECTED]: RE: radical revamping of techpubs> >The same could be said of pacemakers, missile control systems, and a > >host of others. That does not change the fact that in most software > >applications, perceptions of quality are highly subjective.> >> >> >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 > >10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; > >framers@lists.frameusers.com> >> >> > >>Quality is primarily a subjective opinion;> > >>Similarly, whether a product is crap or not is again an opinion, > > not an objective evaluation that can applied in all cases.> >> >When you work in the semi-conductor industry making high-tech > >instruments that are used in fabs (chip fabrication plants), quality > >is not subjective. If the tool stops running after a few thousand > >cycles or a part on the tool fails after only a few months of > >running, then it's objective. A part broke, the Tool shutdown, > >quality is crap, that's not subjective.> >> >TechWriters in my field document the software that runs on these > >types of tools. If you go to a fab, you'll see the type of tools I > >am taking about.> >> >BTW, why don't you identify who you are? You act so sanctimonious > >yet you hide behind a moniker. Have some cohones and tell us who you are.> >> >> >Thank you,> >> >> >Gillian Flato> >Technical Writer (Software)> >nanometrics> >1550 Buckeye Dr.> >Milpitas, CA. 95035> >(408.545.6316> >7 408.232.5911> >* [EMAIL PROTECTED]> >> >> >> >> >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, > >October 19, 2007 9:37 AMTo: Flato, Gillian; > >[EMAIL PROTECTED]: RE: radical revamping of techpubs> > And I know of a CEO who used to either get there first, or let the > > wannabes struggle over the crumbs. Name of Bill Gates. Quality is > > primarily a subjective opinion; witness the 90+% of the population > > of the planet using Windows, despite the occasional Blue Screen of > > Death, or necessary re-booting orre-insta
RE: radical revamping of techpubs
Good point.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> Date: Fri, 19 Oct 2007 11:10:43 -0700> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> From: [EMAIL PROTECTED]> Subject: RE: radical revamping of techpubs> > You're making an assumption that the market is driven by quality. It > is not, though that's certainly a factor. The market is driven even > more by good marketing.> > At 10:58 AM 10/19/2007, Technical Writer wrote:> > >And yet people still buy it. If they did not, issues of quality > >would be irrelevant; only the "quality" items would be purchased, > >the "crap" would languish on the dealer shelves, and we would be > >working rather than having this > >discussion.http://www.tekwrytrs.com/Specializing in the Design, > >Development, and Production of:Technical Documentation - Online > >Content - Enterprise Websites> >> >> >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 > >10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; > >framers@lists.frameusers.com> >> >> >> >I have seen enough bug reports in my time to know that quality is > >not subjective. If the software generates a mile-long list of bugs > >reported by customers and QA people, the software application is crap.> >> >> >Thank you,> >> >> >Gillian Flato> >Technical Writer (Software)> >nanometrics> >1550 Buckeye Dr.> >Milpitas, CA. 95035> >(408.545.6316> >7 408.232.5911> >* [EMAIL PROTECTED]> >> >> >> >> >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, > >October 19, 2007 10:52 AMTo: Flato, Gillian; > >[EMAIL PROTECTED]: RE: radical revamping of techpubs> >The same could be said of pacemakers, missile control systems, and a > >host of others. That does not change the fact that in most software > >applications, perceptions of quality are highly subjective.> >> >> >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 > >10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; > >framers@lists.frameusers.com> >> >> > >>Quality is primarily a subjective opinion;> > >>Similarly, whether a product is crap or not is again an opinion, > > not an objective evaluation that can applied in all cases.> >> >When you work in the semi-conductor industry making high-tech > >instruments that are used in fabs (chip fabrication plants), quality > >is not subjective. If the tool stops running after a few thousand > >cycles or a part on the tool fails after only a few months of > >running, then it's objective. A part broke, the Tool shutdown, > >quality is crap, that's not subjective.> >> >TechWriters in my field document the software that runs on these > >types of tools. If you go to a fab, you'll see the type of tools I > >am taking about.> >> >BTW, why don't you identify who you are? You act so sanctimonious > >yet you hide behind a moniker. Have some cohones and tell us who you are.> >> >> >Thank you,> >> >> >Gillian Flato> >Technical Writer (Software)> >nanometrics> >1550 Buckeye Dr.> >Milpitas, CA. 95035> >(408.545.6316> >7 408.232.5911> >* [EMAIL PROTECTED]> >> >> >> >> >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, > >October 19, 2007 9:37 AMTo: Flato, Gillian; > >[EMAIL PROTECTED]: RE: radical revamping of techpubs> > And I know of a CEO who used to either get there first, or let the > > wannabes struggle over the crumbs. Name of Bill Gates. Quality is > > primarily a subjective opinion; witness the 90+% of the population > > of the planet using Windows, despite the occasional Blue Screen of > > Death, or necessary re-booting orre-installing required. Similarly, > > whether a product is crap or not is again an opinion, not an > > objective evaluation that can applied in all cases. The Debian > > flavor of Linux is considered "the best" by some, and "the worst" > > by some. The opinions are subjective. Everyone TW wants to believe > > that he or she is producing quality documentation that creates a > > warm fuzzy in the user, and makes customers-for-life of the company > > that produces whatever is being documented. I simply suggest a > > reality check may be more useful. If the TW is documenting > > s
RE: radical revamping of techpubs
Yes. It is mandatory that conscientious performance of a particular work task include--at a minimum--an acceptable level of quality. Without the intervention of the QA department. The Theory X management view that people are lazy, don't care about quality, and will do everything possible to avoid work unless micromanaged every moment is obsolete, and indicative of little more than a failure of management.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> Subject: RE: radical revamping of techpubs> Date: Fri, 19 Oct 2007 14:09:08 -0400> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> > Got to chime in on this interesting discussion.> > Technical Writer wrote:> > In a world in which dynamic online help files are rapidly replacing hard> copy documents, it seems more useful to focus on developing a skill set> that enables high-volume production of acceptable quality content,> rather than obsessing over trivial (to most users) details of grammar,> construction, or voice.> > I see your point, but I think this is polarizing a non-issue. I don't> think "high-volume production of acceptable quality content" and> "details of grammar, construction, or voice" are incompatible goals. If> I am hiring a technical writer, I want someone who can pay attention to> both. In rapid development environments (whatever you care to call that> model), there are plenty of tools to help automate your high-volume> production. It doesn't take longer to write clearly and consistently.> And I don't think you can safely say "the majority of users" don't care.> Depends on the users. Depends on the product. Personally, I can blink at> a few errors but when they become egregious, I think "Jeez Louise, they> can't even run a spell-checker? What other details can't this company be> bothered with?" The "dynamic online help files" are part of the product,> and I start to question quality control for the whole product.> > Thanks for the thoughtful discussion, everyone.> > Dorianne> _ Windows Live Hotmail and Microsoft Office Outlook – together at last. Get it now. http://office.microsoft.com/en-us/outlook/HA102225181033.aspx?pid=CL100626971033___ 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
Exactly. And the desire to buy--the want and the need--are in the province of marketing. That is why the makers of some of the shoddiest goods on the planet prattle on about quality, as if it were a thing-in-itself. In many cases, it is a subjective perception and subjective opinion.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> Date: Fri, 19 Oct 2007 14:06:06 -0400> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]> Subject: Re: radical revamping of techpubs> CC: [EMAIL PROTECTED]; framers@lists.frameusers.com> > People buy things out of need and want. If the quality sucks, and they> need it, what are they going to do? If an insulin pump eats batteries> at a 20% higher rate than advertised, the quality sucks, but that> doesn't mean that the product isn't needed. It's up to the company to> fix the quality flaws and bring the product up to market expectation.> > No product is ever perfect. That's near impossible to do. But darn> close is attainable.> > And quality is very much objective in most products given that you can> collect quality metrics on the products themselves, log bugs, measure> impact, etc.> > On 10/19/07, Technical Writer <[EMAIL PROTECTED]> wrote:> >> > And yet people still buy it. If they did not, issues of quality would be irrelevant; only the "quality" items would be purchased, the "crap" would languish on the dealer shelves, and we would be working rather than having this discussion.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> > -- > Bill Swallow> HATT List Owner> WWP-Users List Owner> Senior Member STC, TechValley Chapter> STC Single-Sourcing SIG Manager> http://techcommdood.blogspot.com _ Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hotmailnews___ 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
My inference is that hardware would not have been standardized without Microsoft or some other aggressive, unifying business entity. I've actually had good luck with PCs, but I've been a Mac user since 1984 and an Apple user for four years before that, a UNIX user about the same length of time, and have built my own machines for close to fifteen years now. Buy Intel motherboards :) and try again. --- Ron Miller <[EMAIL PROTECTED]> wrote: > Your inference suggests that hardware would have stayed expensive > without Microsoft. I don't buy that. In my view, hardware would have > dropped regardless because the price of the components dropped over > time, completely independent from the PC's relationship to Microsoft. > > In fact, I would maintain that competition in the OS/Office > productivity space in the 90s would have eventually resulted in > making these items commodities, which would have reduced the overall > cost of ownership dramatically. Proof of this is the number of free > office productivity and operating systems that have developed in > today's more open environment. These products would have developed > sooner had Microsoft not been allowed to artificially control pricing > and the market. > > I would agree that there it would have created a more difficult > environment for us as tech writer to produce documentation, but I > have the feeling it would have worked itself out, just as it has with > browser-based help that works regardless of the operating system in > place. As for Apple, people continue to buy the product in spite of > its higher price because it isn't a one for one comparison. There is > a quality factor, ease of use and stability that I've yet to see > matched in a PC. And I speak as someone who is relatively recent Mac > owner, but has used PCs since 1985 > > 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 19, 2007, at 2:50 PM, Chris Borokowski wrote: > > > I'm somewhat thankful they did, as the result was a standardization > of > > hardware that allows $500 to buy a better quality machine than a > $1500 > > Macintosh or $2500 custom UNIX. Sometimes aggression in business > can > > produce very fortunate results for us little people. > > > > --- Ron Miller <[EMAIL PROTECTED]> wrote: > > > >> In my view, the only reason Windows has dominated personal > computing > >> is because Microsoft bullied hardware company into selling its > >> products. It told computer manufacturers throughout the 90s when > it > >> built its domination to either use only Windows or to have to pay > >> more for each copy if they didn't. > > > > 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/ > > ronsmiller%40comcast.net > > > > Send administrative questions to [EMAIL PROTECTED] Visit > > http://www.frameusers.com/ for more resources and info. > > 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.
RE: radical revamping of techpubs
Actually, no, that's not the case, Gillian; Tekwryter's emails directly to me have been well-formatted. I think this is more an effect of the listserve software doing something unexpected. John At 04:04 PM 10/19/2007, Flato, Gillian wrote: One of the aspects of good Tech Writing is usability and formatting of text to make it easy to read for the end-user. Tekwryter can't even make an email readable, as you can see by his response below. I won't hold my breath that his documents are good quality. I guess the email below is a product of an Agile/XP email system. He also might consider getting someone to QA his email posts. -Gillian -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Technical Writer Sent: Friday, October 19, 2007 3:56 PM To: [EMAIL PROTECTED]; framers@lists.frameusers.com Subject: RE: radical revamping of techpubs Good point.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> Date: Fri, 19 Oct 2007 11:10:43 -0700> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> From: [EMAIL PROTECTED]> Subject: RE: radical revamping of techpubs> > You're making an assumption that the market is driven by quality. It > is not, though that's certainly a factor. The market is driven even > more by good marketing.> > At 10:58 AM 10/19/2007, Technical Writer wrote:> > >And yet people still buy it. If they did not, issues of quality > >would be irrelevant; only the "quality" items would be purchased, > >the "crap" would languish on the dealer shelves, and we would be > >working rather than having this > >discussion.http://www.tekwrytrs.com/Specializing in the Design, > >Development, and Production of:Technical Documentation - Online > >Content - Enterprise Websites> >> >> >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 > >10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; > >framers@lists.frameusers.com> >> >> >> >I have seen enough bug reports in my time to know that quality is > >not subjective. If the software generates a mile-long list of bugs > >reported by customers and QA people, the software application is crap.> >> >> >Thank you,> >> >> >Gillian Flato> >Technical Writer (Software)> >nanometrics> >1550 Buckeye Dr.> >Milpitas, CA. 95035> >(408.545.6316> >7 408.232.5911> >* [EMAIL PROTECTED]> >> >> >> >> >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, > >October 19, 2007 10:52 AMTo: Flato, Gillian; > >[EMAIL PROTECTED]: RE: radical revamping of techpubs> >The same could be said of pacemakers, missile control systems, and a > >host of others. That does not change the fact that in most software > >applications, perceptions of quality are highly subjective.> >> >> >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 > >10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; > >framers@lists.frameusers.com> >> >> > >>Qual ity is primarily a subjective opinion;> > >>Similarly, whether a product is crap or not is again an opinion, > > not an objective evaluation that can applied in all cases.> >> >When you work in the semi-conductor industry making high-tech > >instruments that are used in fabs (chip fabrication plants), quality > >is not subjective. If the tool stops running after a few thousand > >cycles or a part on the tool fails after only a few months of > >running, then it's objective. A part broke, the Tool shutdown, > >quality is crap, that's not subjective.> >> >TechWriters in my field document the software that runs on these > >types of tools. If you go to a fab, you'll see the type of tools I > >am taking about.> >> >BTW, why don't you identify who you are? You act so sanctimonious > >yet you hide behind a moniker. Have some cohones and tell us who you are.> >> >> >Thank you,> >> >> >Gillian Flato> >Technical Writer (Software)> >nanometrics> >1550 Buckeye Dr.> >Milpitas, CA. 95035> >(408.545.6316> >7 408.232.5911> >* [EMAIL PROTECTED]> >> >> >> >> >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, > >October 19, 2007 9:37 AMTo: Flato, Gillian; > >[EMAIL PROTECTED]: RE: radical revamping of techpubs> > And I know of a CEO who used to either get there first, or let the > > wannabes
RE: radical revamping of techpubs
As there is an entire industry based on usability. Also the first to go when the belt needs tightening, because they are perceived as being "nice to have when the economy is good, but otherwise not particularly useful." To believe that a secondary industry is necessary to assure an acceptable level of quality in production is impoverished. Quality goods can be produced by motivated, competent workers without a QA overseer. > Date: Fri, 19 Oct 2007 14:03:01 -0400> From: [EMAIL PROTECTED]> To: [EMAIL > PROTECTED]> Subject: Re: radical revamping of techpubs> CC: [EMAIL > PROTECTED]; framers@lists.frameusers.com> > I can't see how quality can > possibly be subjective if there's an> entire occupation devoted to assuring > it. Perhaps TW has only worked> in environments where "quality" is merely a > buzzword.> > On 10/19/07, Flato, Gillian <[EMAIL PROTECTED]> wrote:> > I have > seen enough bug reports in my time to know that quality is not> > subjective. > If the software generates a mile-long list of bugs reported> > by customers > and QA people, the software application is crap.> > -- > Bill Swallow> HATT > List Owner> WWP-Users List Owner> Senior Member STC, TechValley Chapter> STC > Single-Sourcing SIG Manager> http://techcommdood.blogspot.com _ Help yourself to FREE treats served up daily at the Messenger Café. Stop by today. http://www.cafemessenger.com/info/info_sweetstuff2.html?ocid=TXT_TAGLM_OctWLtagline___ 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
Your inference suggests that hardware would have stayed expensive without Microsoft. I don't buy that. In my view, hardware would have dropped regardless because the price of the components dropped over time, completely independent from the PC's relationship to Microsoft. In fact, I would maintain that competition in the OS/Office productivity space in the 90s would have eventually resulted in making these items commodities, which would have reduced the overall cost of ownership dramatically. Proof of this is the number of free office productivity and operating systems that have developed in today's more open environment. These products would have developed sooner had Microsoft not been allowed to artificially control pricing and the market. I would agree that there it would have created a more difficult environment for us as tech writer to produce documentation, but I have the feeling it would have worked itself out, just as it has with browser-based help that works regardless of the operating system in place. As for Apple, people continue to buy the product in spite of its higher price because it isn't a one for one comparison. There is a quality factor, ease of use and stability that I've yet to see matched in a PC. And I speak as someone who is relatively recent Mac owner, but has used PCs since 1985 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 19, 2007, at 2:50 PM, Chris Borokowski wrote: I'm somewhat thankful they did, as the result was a standardization of hardware that allows $500 to buy a better quality machine than a $1500 Macintosh or $2500 custom UNIX. Sometimes aggression in business can produce very fortunate results for us little people. --- Ron Miller <[EMAIL PROTECTED]> wrote: In my view, the only reason Windows has dominated personal computing is because Microsoft bullied hardware company into selling its products. It told computer manufacturers throughout the 90s when it built its domination to either use only Windows or to have to pay more for each copy if they didn't. 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/ 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.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 market is also driven by price, availability, and value (=quality for the price), but pervasive marketing and cut-throat competition can trump. Rene John Hedtke <[EMAIL PROTECTED]> wrote: You're making an assumption that the market is driven by quality. It is not, though that's certainly a factor. The market is driven even more by good marketing. At 10:58 AM 10/19/2007, Technical Writer wrote: >And yet people still buy it. If they did not, issues of quality >would be irrelevant; only the "quality" items would be purchased, >the "crap" would languish on the dealer shelves, and we would be >working rather than having this >discussion.http://www.tekwrytrs.com/Specializing in the Design, >Development, and Production of:Technical Documentation - Online >Content - Enterprise Websites > > >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 >10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; >framers@lists.frameusers.com > > > >I have seen enough bug reports in my time to know that quality is >not subjective. If the software generates a mile-long list of bugs >reported by customers and QA people, the software application is crap. > > >Thank you, > > >Gillian Flato >Technical Writer (Software) >nanometrics >1550 Buckeye Dr. >Milpitas, CA. 95035 >(408.545.6316 >7 408.232.5911 >* [EMAIL PROTECTED] > > > > >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, >October 19, 2007 10:52 AMTo: Flato, Gillian; >[EMAIL PROTECTED]: RE: radical revamping of techpubs >The same could be said of pacemakers, missile control systems, and a >host of others. That does not change the fact that in most software >applications, perceptions of quality are highly subjective. > > >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 >10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; >framers@lists.frameusers.com > > > >>Quality is primarily a subjective opinion; > >>Similarly, whether a product is crap or not is again an opinion, > not an objective evaluation that can applied in all cases. > >When you work in the semi-conductor industry making high-tech >instruments that are used in fabs (chip fabrication plants), quality >is not subjective. If the tool stops running after a few thousand >cycles or a part on the tool fails after only a few months of >running, then it's objective. A part broke, the Tool shutdown, >quality is crap, that's not subjective. > >TechWriters in my field document the software that runs on these >types of tools. If you go to a fab, you'll see the type of tools I >am taking about. > >BTW, why don't you identify who you are? You act so sanctimonious >yet you hide behind a moniker. Have some cohones and tell us who you are. > > >Thank you, > > >Gillian Flato >Technical Writer (Software) >nanometrics >1550 Buckeye Dr. >Milpitas, CA. 95035 >(408.545.6316 >7 408.232.5911 >* [EMAIL PROTECTED] > > > > >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, >October 19, 2007 9:37 AMTo: Flato, Gillian; >[EMAIL PROTECTED]: RE: radical revamping of techpubs > And I know of a CEO who used to either get there first, or let the > wannabes struggle over the crumbs. Name of Bill Gates. Quality is > primarily a subjective opinion; witness the 90+% of the population > of the planet using Windows, despite the occasional Blue Screen of > Death, or necessary re-booting orre-installing required. Similarly, > whether a product is crap or not is again an opinion, not an > objective evaluation that can applied in all cases. The Debian > flavor of Linux is considered "the best" by some, and "the worst" > by some. The opinions are subjective. Everyone TW wants to believe > that he or she is producing quality documentation that creates a > warm fuzzy in the user, and makes customers-for-life of the company > that produces whatever is being documented. I simply suggest a > reality check may be more useful. If the TW is documenting > software, perhaps he or she should change fields to one with a > slower pace of life (and writing). The option is to accept the > realities of the marketplace, and how those influence and constrain > the production of technical documentation. In a world in which > dynamic onlne help files are rapidly replacing hard copy documents, > it seems more useful to focus on developing a skill set that > enables high-volume production of acceptable quality content, > rather than obsessing over trivial (to most users) details of > grammar, construction, or voice. In that direction may lie the >
RE: radical revamping of techpubs
You're making an assumption that the market is driven by quality. It is not, though that's certainly a factor. The market is driven even more by good marketing. At 10:58 AM 10/19/2007, Technical Writer wrote: And yet people still buy it. If they did not, issues of quality would be irrelevant; only the "quality" items would be purchased, the "crap" would languish on the dealer shelves, and we would be working rather than having this discussion.http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; framers@lists.frameusers.com I have seen enough bug reports in my time to know that quality is not subjective. If the software generates a mile-long list of bugs reported by customers and QA people, the software application is crap. Thank you, Gillian Flato Technical Writer (Software) nanometrics 1550 Buckeye Dr. Milpitas, CA. 95035 (408.545.6316 7 408.232.5911 * [EMAIL PROTECTED] From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, October 19, 2007 10:52 AMTo: Flato, Gillian; [EMAIL PROTECTED]: RE: radical revamping of techpubs The same could be said of pacemakers, missile control systems, and a host of others. That does not change the fact that in most software applications, perceptions of quality are highly subjective. Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; framers@lists.frameusers.com >>Quality is primarily a subjective opinion; >>Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. When you work in the semi-conductor industry making high-tech instruments that are used in fabs (chip fabrication plants), quality is not subjective. If the tool stops running after a few thousand cycles or a part on the tool fails after only a few months of running, then it's objective. A part broke, the Tool shutdown, quality is crap, that's not subjective. TechWriters in my field document the software that runs on these types of tools. If you go to a fab, you'll see the type of tools I am taking about. BTW, why don't you identify who you are? You act so sanctimonious yet you hide behind a moniker. Have some cohones and tell us who you are. Thank you, Gillian Flato Technical Writer (Software) nanometrics 1550 Buckeye Dr. Milpitas, CA. 95035 (408.545.6316 7 408.232.5911 * [EMAIL PROTECTED] From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, October 19, 2007 9:37 AMTo: Flato, Gillian; [EMAIL PROTECTED]: RE: radical revamping of techpubs And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority.< From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market
RE: radical revamping of techpubs
No, I've known that for quite some time. It is built on BSD, hacked with Mach on a ton of libraries, and it's nowhere near as stable as BSD or as logically consistent. My primary reason for avoiding Apple is the company and, I almost forgot, the sanctimonious attitudes of its users ;) --- Neil Tubb <[EMAIL PROTECTED]> wrote: > Clearly Chris hasn't used a Mac since System 7...;-)...might be > interested to know that OSX is built on BSD! 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.
RE: radical revamping of techpubs
True enough. :) At 11:23 AM 10/19/2007, Rene Stephenson wrote: The market is also driven by price, availability, and value (=quality for the price), but pervasive marketing and cut-throat competition can trump. Rene John Hedtke <[EMAIL PROTECTED]> wrote: You're making an assumption that the market is driven by quality. It is not, though that's certainly a factor. The market is driven even more by good marketing. At 10:58 AM 10/19/2007, Technical Writer wrote: >And yet people still buy it. If they did not, issues of quality >would be irrelevant; only the "quality" items would be purchased, >the "crap" would languish on the dealer shelves, and we would be >working rather than having this >discussion.http://www.tekwrytrs.com/Specializing in the Design, >Development, and Production of:Technical Documentation - Online >Content - Enterprise Websites > > >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 >10:55:33 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; >framers@lists.frameusers.com > > > >I have seen enough bug reports in my time to know that quality is >not subjective. If the software generates a mile-long list of bugs >reported by customers and QA people, the software application is crap. > > >Thank you, > > >Gillian Flato >Technical Writer (Software) >nanometrics >1550 Buckeye Dr. >Milpitas, CA. 95035 >(408.545.6316 >7 408.232.5911 >* [EMAIL PROTECTED] > > > > >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, >October 19, 2007 10:52 AMTo: Flato, Gillian; >[EMAIL PROTECTED]: RE: radical revamping of techpubs >The same could be said of pacemakers, missile control systems, and a >host of others. That does not change the fact that in most software >applications, perceptions of quality are highly subjective. > > >Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 >10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; >framers@lists.frameusers.com > > > >>Quality is primarily a subjective opinion; > >>Similarly, whether a product is crap or not is again an opinion, > not an objective evaluation that can applied in all cases. > >When you work in the semi-conductor industry making high-tech >instruments that are used in fabs (chip fabrication plants), quality >is not subjective. If the tool stops running after a few thousand >cycles or a part on the tool fails after only a few months of >running, then it's objective. A part broke, the Tool shutdown, >quality is crap, that's not subjective. > >TechWriters in my field document the software that runs on these >types of tools. If you go to a fab, you'll see the type of tools I >am taking about. > >BTW, why don't you identify who you are? You act so sanctimonious >yet you hide behind a moniker. Have some cohones and tell us who you are. > > >Thank you, > > >Gillian Flato >Technical Writer (Software) >nanometrics >1550 Buckeye Dr. >Milpitas, CA. 95035 >(408.545.6316 >7 408.232.5911 >* [EMAIL PROTECTED] > > > > >From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, >October 19, 2007 9:37 AMTo: Flato, Gillian; >[EMAIL PROTECTED]: RE: radical revamping of techpubs > And I know of a CEO who used to either get there first, or let the > wannabes struggle over the crumbs. Name of Bill Gates. Quality is > primarily a subjective opinion; witness the 90+% of the population > of the planet using Windows, despite the occasional Blue Screen of > Death, or necessary re-booting orre-installing required. Similarly, > whether a product is crap or not is again an opinion, not an > objective evaluation that can applied in all cases. The Debian > flavor of Linux is considered "the best" by some, and "the worst" > by some. The opinions are subjective. Everyone TW wants to believe > that he or she is producing quality documentation that creates a > warm fuzzy in the user, and makes customers-for-life of the company > that produces whatever is being documented. I simply suggest a > reality check may be more useful. If the TW is documenting > software, perhaps he or she should change fields to one with a > slower pace of life (and writing). The option is to accept the > realities of the marketplace, and how those influence and constrain > the production of technical documentation. In a world in which > dynamic onlne help files are rapidly replacing hard copy documents, > it seems more useful to focus on developing a skill set that > enables high-volume production of acceptable quality content, > rather than obsessing over trivial (to most users) details of > grammar, construction, or voice. In that direction may lie t
Re: radical revamping of techpubs
In my view, the only reason Windows has dominated personal computing is because Microsoft bullied hardware company into selling its products. It told computer manufacturers throughout the 90s when it built its domination to either use only Windows or to have to pay more for each copy if they didn't. With small margins on PCs, hardware companies were forced to comply until a lawsuit put a stop to this practice. By that time, however, Windows had built a huge installed base, making it very difficult to move an entrenched player (even when the player became entrenched through less than honest means). Therefore Microsoft's dominance had little to do with having a better image or even better marketing, it had to do with a business plan to bully the market into buying its products. It worked, but Windows dominance in the OS arena has little do with its quality and even less to do with its ease of use. 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 19, 2007, at 2:37 PM, Chris Borokowski wrote: Another way to say this might, the market is driven by perceived quality of product as a product. Microsoft Windows is not as stable as BSD, but it installs easily and lets the average user get up and running quickly while maintaining high backward compatibility. Is that higher quality, or lower quality? Not so clear. However, for the task at hand, defined by the purchasing audience, it is a more apt fit. I believe that the market is driven by image, including the marketing you mention, but part of that is a perception of quality as defined by the needs of the users. I'm sure that did nothing to simplify this debate. Feel free to flame me off-list for such blatant non-helpfulness. --- John Hedtke <[EMAIL PROTECTED]> wrote: You're making an assumption that the market is driven by quality. It is not, though that's certainly a factor. The market is driven even more by good marketing. 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/ 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.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
Most applications hover somewhere between excellent and crap. The ones that generate the mile-long grievances are crap, and the ones that people treasure (and hoard on their thumb drives) for a decade are excellent. --- "Flato, Gillian" <[EMAIL PROTECTED]> wrote: > I have seen enough bug reports in my time to know that quality is not > subjective. If the software generates a mile-long list of bugs > reported > by customers and QA people, the software application is crap. 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.
RE: radical revamping of techpubs
The same could be said of pacemakers, missile control systems, and a host of others. That does not change the fact that in most software applications, perceptions of quality are highly subjective. Subject: RE: radical revamping of techpubsDate: Fri, 19 Oct 2007 10:09:42 -0700From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; framers@lists.frameusers.com >>Quality is primarily a subjective opinion; >>Similarly, whether a product is crap or not is again an opinion, not an >>objective evaluation that can applied in all cases. When you work in the semi-conductor industry making high-tech instruments that are used in fabs (chip fabrication plants), quality is not subjective. If the tool stops running after a few thousand cycles or a part on the tool fails after only a few months of running, then it's objective. A part broke, the Tool shutdown, quality is crap, that's not subjective. TechWriters in my field document the software that runs on these types of tools. If you go to a fab, you'll see the type of tools I am taking about. BTW, why don't you identify who you are? You act so sanctimonious yet you hide behind a moniker. Have some cohones and tell us who you are. Thank you, Gillian Flato Technical Writer (Software) nanometrics 1550 Buckeye Dr. Milpitas, CA. 95035 (408.545.6316 7 408.232.5911 * [EMAIL PROTECTED] From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Friday, October 19, 2007 9:37 AMTo: Flato, Gillian; [EMAIL PROTECTED]: RE: radical revamping of techpubs And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority.< From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wisely fired him and put a new CEO at the helm.> > > -Gillian> > Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! Try now! _ Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hotmailnews___ 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
Doesn't it depend on what the competition is? --- Technical Writer <[EMAIL PROTECTED]> wrote: > And yet people still buy it. 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.
Re: radical revamping of techpubs
Bill Gates, first to market? Gates has proven anything by innovative. He's the quintessential, 'let the other guys put it on the market and we'll steal it and market it better.' DOS? He bought the company? Windows? Stole the idea from Apple (who stole it from Xerox Park) Internet Explorer? Netscape was their first. The Zune? Don't make me laugh. Gates has been watching and copying for as long as I remember. 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 19, 2007, at 12:37 PM, Technical Writer wrote: And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority. < From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wisely fired him and put a new CEO at the helm.> > > -Gillian> > _ Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! http://onecare.live.com/standard/en-us/purchase/trial.aspx? s_cid=wl_hotmailnews___ 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.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
>>Quality is primarily a subjective opinion;
>>Similarly, whether a product is crap or not is again an opinion, not
an objective evaluation that can applied in all cases.
When you work in the semi-conductor industry making high-tech
instruments that are used in fabs (chip fabrication plants), quality is
not subjective. If the tool stops running after a few thousand cycles or
a part on the tool fails after only a few months of running, then it's
objective. A part broke, the Tool shutdown, quality is crap, that's not
subjective.
TechWriters in my field document the software that runs on these types
of tools. If you go to a fab, you'll see the type of tools I am taking
about.
BTW, why don't you identify who you are? You act so sanctimonious yet
you hide behind a moniker. Have some cohones and tell us who you are.
Thank you,
<mailto:[EMAIL PROTECTED]>
Gillian Flato
Technical Writer (Software)
nanometrics
1550 Buckeye Dr.
Milpitas, CA. 95035
(408.545.6316
7 408.232.5911
* [EMAIL PROTECTED] <mailto:[EMAIL PROTECTED]> .com
mailto:[EMAIL PROTECTED]>
From: Technical Writer [mailto:[EMAIL PROTECTED]
Sent: Friday, October 19, 2007 9:37 AM
To: Flato, Gillian; framers@lists.frameusers.com
Subject: RE: radical revamping of techpubs
And I know of a CEO who used to either get there first, or let
the wannabes struggle over the crumbs. Name of Bill Gates.
Quality is primarily a subjective opinion; witness the 90+% of
the population of the planet using Windows, despite the occasional Blue
Screen of Death, or necessary re-booting orre-installing required.
Similarly, whether a product is crap or not is again an opinion, not an
objective evaluation that can applied in all cases. The Debian flavor of
Linux is considered "the best" by some, and "the worst" by some. The
opinions are subjective.
Everyone TW wants to believe that he or she is producing quality
documentation that creates a warm fuzzy in the user, and makes
customers-for-life of the company that produces whatever is being
documented. I simply suggest a reality check may be more useful.
If the TW is documenting software, perhaps he or she should
change fields to one with a slower pace of life (and writing). The
option is to accept the realities of the marketplace, and how those
influence and constrain the production of technical documentation. In a
world in which dynamic onlne help files are rapidly replacing hard copy
documents, it seems more useful to focus on developing a skill set that
enables high-volume production of acceptable quality content, rather
than obsessing over trivial (to most users) details of grammar,
construction, or voice.
In that direction may lie the future of TW--get it written, get
it online, and concentrate on the Pareto principle of satisfying the
needs of the majority of users rather than obsessing over the subjective
opinions of the minority.
< From: [EMAIL PROTECTED]
> To: [EMAIL PROTECTED]; framers@lists.frameusers.com
>
> ...or similar biggies realize that time-to-market is
everything,
>
> Time-to-market is not everything if you sacrifice quality. If
you're first on the market but your product is crap, the fact that you
were first on the market is irrelevant.
>
> I know a CEO who got fired because all he cared about is being
first on the market but his products were crap and failed often. Other
company's that were slower to market but turned out quality products,
stole marketshare from that company. The company almost went under until
the board of Directors wisely fired him and put a new CEO at the helm.
>
>
> -Gillian
>
>
Boo! Scare away worms, viruses and so much more! Try Windows
Live OneCare! Try now!
<http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hot
mailnews>
___
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 presumption was made that Microsoft has market share due to time-to-market push by Gates, and that is a gross oversimplification. It has a lot more to do with cut-throat marketing tactics and industrial espionage (end justifies the means to Gates) than it does with simply driving a product forward, although Gates' time-to-market priorities do explain the fact that people generally avoid new MS products for 6-12 mo until the service packs that fix the most egregious bugs are available. Without ample testing, lower quality products are released, and after repeatedly seeing this, users are wary to buy the new versions upon release. The same goes for documentation - many people avoid the documentation that comes with a new release in favor of either after-market docs or the company's updated post-release documents. Microsoft's answer to this has been to force upgrades by refusing to issue any new licenses on the more stable, older version as soon as the new one comes out, regardless of the bugs. That is why MS gets reamed about Vista by the "Dilberts" (borrowing the term from earlier in this thread). It is costly in time (and therefore manhours and therefore money) to have to work around crappy products or wade through crappy documentation. Continuing to produce crap and fix it on the second pass causes a loss of faith in the customer base, and they start looking for more hassle-free alternatives. Then, the company can either choose to be more conscientious and earn the loyalty of their customers, or they can bully the competition out of the market to force the customer into a no-other-viable-choice scenario. MS has done the latter more than the former. Rene ___ 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
I'm not sure the question here is one of quality as much as different purposes. If you want most stuff to install quickly and work the first time, want flexibility about what hardware you can use, and want compatibility with most people out there, Windows is a clear winner, and most users never see a blue screen of death. If you want a UNIX-like operating system that's free and gives you some flexibility of hardware, but don't mind fiddling with software and OS settings, Linux is a good choice. If you want a stable snazzy operating system, and want few hardware choices and don't care what it costs you or how often it breaks down, you pick Macintosh. I think there's an important lesson there for TWs. User profiles are generally a big time-waster when people make up users complete with names and histories. But recognizing the different general functions users want to fulfil, and as a result the choices they make, is really important. Not everyone wants the bulletproof operating system. If they did, we'd all run BSD ;) --- Technical Writer <[EMAIL PROTECTED]> wrote: > Quality is primarily a subjective opinion; witness the 90+% of the > population of the planet using Windows, despite the occasional Blue > Screen of Death, or necessary re-booting orre-installing required. > Similarly, whether a product is crap or not is again an opinion, not > an objective evaluation that can applied in all cases. The Debian > flavor of Linux is considered "the best" by some, and "the worst" by > some. The opinions are subjective. 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.
Re: radical revamping of techpubs
I agree, and if there's one reason many people think technical writing has a bad name, it's this. The churned-out documentation where the writer is left with so little time and support they create a transcription of the obvious, with little informational content or sense of how they can make the users relax and understand the application on a power user level. Most of the documentation I read is so horrible it's beyond conception, but I think that this mentality of showing up late and churning out the manual, which I call WTFM, is at fault, not necessarily the writer. (I have to add that in many cases, people who are not writers are pressed into service as writers, and their dislike of that situation causes more problems than their level of talent and education for it.) --- Rene Stephenson <[EMAIL PROTECTED]> wrote: > And that's exactly why so much of the documentation is > frustrating for the customer to use. You can't generate technically > correct content that is usable and well-planned and free of glaring > typos and grammatical errors when you are only given an average of 30 > minutes per page of output. 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.
RE: radical revamping of techpubs
Perhaps.
However, I can speak from the experience I had at a company where the
manager of documentation attended design-phase meetings for the products, and
then she assigned a writer when a prototype was available. The doc mgr was
able to provide key input about the user base and do some basic QA of GUI
concepts that eliminated a lot of the inconsistency issues within the GUIs,
and she provided ideas for combining GUIs or menu architecture in ways that
made sense to the users, based on comments we received in (oddly enough)
documentation feedback forms. (Apparently people will complain whenever they
see an opening, in hopes that someone will pass it along.) When a prototype
was available, the doc mgr then assigned a writer and handed off to the writer
at a product meeting.
After about 6 months of handling products this way, product managers
commented positively about the effect on the product of having the doc mgr
involved. They didn't have as many issues with rework at a point when the code
was more complicated. They got better feedback from customers when marketing
presented prototypes. QA was pleased with the improved consistency and
usability of the screens. Engineers, while initially resistant to the idea,
discovered that they could leverage TWs for screen checks, freeing up
themeselves for more technical efforts in development.
Of course, the impact on documentation itself of earlier involvement in the
process was readily apparent. TWs knew more about the subject product, because
they had more time to learn it before the final delivery. Extending the
timeline for the documents by involving TWs earlier in the process resulted in
higher quality documents from a technical standpoint as well as from an
organizational/doc structure/writing quality standpoint. It became possible to
deliver high-quality documentation AT the general availability (GA) date of
the product, rather than doc lagging behind. And of course, the customer
benefited.
It may be an old argument, but when it is put into practice, the proof is in
the pudding. It's an old argument because it stands the test of time and trial.
Rene Stephenson
Technical Writer <[EMAIL PROTECTED]> wrote:.hmmessage P { margin:0px;
padding:0px } body.hmmessage { FONT-SIZE: 10pt; FONT-FAMILY:Tahoma }
The argument that TWs should be involved from the design inception is an old
one, and not often found outside the circle of TWs. The reason is simple; in
the olden times when the waterfall was the design method of choice, the
docs--and the app--pretty much stayed the same. And most of both failed
miserably.
In 2007, agile development is proliferating, and RAD and XP are the methods
of choice for initial prototyping and proof-of-concept. The reason some 70% of
software development projects fail is not that it is especially difficult to
write good apps; it is because the majority of those apps are so poorly
designed that they don't do anything useful. With RAD, it is more useful to
develop a working prototype, and let the people paying the bills see what they
are going to get. THEN is the time to involve TWs--at the same time it is
handed off the Java Dilberts.
-
Date: Thu, 18 Oct 2007 17:27:59 -0700
From: [EMAIL PROTECTED]
Subject: Re: radical revamping of techpubs
To: [EMAIL PROTECTED]
CC: [EMAIL PROTECTED]; framers@lists.frameusers.com; [EMAIL PROTECTED]
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?"
-
Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! Try
now!
___
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
RE: radical revamping of techpubs
Got to chime in on this interesting discussion. Technical Writer wrote: In a world in which dynamic online help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. I see your point, but I think this is polarizing a non-issue. I don't think "high-volume production of acceptable quality content" and "details of grammar, construction, or voice" are incompatible goals. If I am hiring a technical writer, I want someone who can pay attention to both. In rapid development environments (whatever you care to call that model), there are plenty of tools to help automate your high-volume production. It doesn't take longer to write clearly and consistently. And I don't think you can safely say "the majority of users" don't care. Depends on the users. Depends on the product. Personally, I can blink at a few errors but when they become egregious, I think "Jeez Louise, they can't even run a spell-checker? What other details can't this company be bothered with?" The "dynamic online help files" are part of the product, and I start to question quality control for the whole product. Thanks for the thoughtful discussion, everyone. Dorianne -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Technical Writer Sent: Friday, October 19, 2007 12:37 PM To: [EMAIL PROTECTED]; framers@lists.frameusers.com Subject: RE: radical revamping of techpubs And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority. < From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wisely fired him and put a new CEO at the helm.> > > -Gillian> > _ Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hotmailnews___ 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/dorianne.gutierrez%40polarislibrary.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
RE: radical revamping of techpubs
Au contraire, I think that's a very good way to put it, Chris. John At 11:37 AM 10/19/2007, Chris Borokowski wrote: Another way to say this might, the market is driven by perceived quality of product as a product. Microsoft Windows is not as stable as BSD, but it installs easily and lets the average user get up and running quickly while maintaining high backward compatibility. Is that higher quality, or lower quality? Not so clear. However, for the task at hand, defined by the purchasing audience, it is a more apt fit. I believe that the market is driven by image, including the marketing you mention, but part of that is a perception of quality as defined by the needs of the users. I'm sure that did nothing to simplify this debate. Feel free to flame me off-list for such blatant non-helpfulness. --- John Hedtke <[EMAIL PROTECTED]> wrote: > You're making an assumption that the market is driven by quality. It > is not, though that's certainly a factor. The market is driven even > more by good marketing. 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/john%40hedtke.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. 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
Another way to say this might, the market is driven by perceived quality of product as a product. Microsoft Windows is not as stable as BSD, but it installs easily and lets the average user get up and running quickly while maintaining high backward compatibility. Is that higher quality, or lower quality? Not so clear. However, for the task at hand, defined by the purchasing audience, it is a more apt fit. I believe that the market is driven by image, including the marketing you mention, but part of that is a perception of quality as defined by the needs of the users. I'm sure that did nothing to simplify this debate. Feel free to flame me off-list for such blatant non-helpfulness. --- John Hedtke <[EMAIL PROTECTED]> wrote: > You're making an assumption that the market is driven by quality. It > is not, though that's certainly a factor. The market is driven even > more by good marketing. 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.
RE: radical revamping of techpubs
Clearly Chris hasn't used a Mac since System 7...;-)...might be interested to know that OSX is built on BSD! Most users "never see a blue screen of death"? Be serious. But I suppose this is all off topic... Neil -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] ] On Behalf Of Chris Borokowski Sent: Friday, October 19, 2007 12:50 PM To: framers@lists.frameusers.com Subject: RE: radical revamping of techpubs I'm not sure the question here is one of quality as much as different purposes. If you want most stuff to install quickly and work the first time, want flexibility about what hardware you can use, and want compatibility with most people out there, Windows is a clear winner, and most users never see a blue screen of death. If you want a UNIX-like operating system that's free and gives you some flexibility of hardware, but don't mind fiddling with software and OS settings, Linux is a good choice. If you want a stable snazzy operating system, and want few hardware choices and don't care what it costs you or how often it breaks down, you pick Macintosh. I think there's an important lesson there for TWs. User profiles are generally a big time-waster when people make up users complete with names and histories. But recognizing the different general functions users want to fulfil, and as a result the choices they make, is really important. Not everyone wants the bulletproof operating system. If they did, we'd all run BSD ;) --- Technical Writer <[EMAIL PROTECTED]> wrote: > Quality is primarily a subjective opinion; witness the 90+% of the > population of the planet using Windows, despite the occasional Blue > Screen of Death, or necessary re-booting orre-installing required. > Similarly, whether a product is crap or not is again an opinion, not > an objective evaluation that can applied in all cases. The Debian > flavor of Linux is considered "the best" by some, and "the worst" by > some. The opinions are subjective. 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/neil.tubb%40solacesy stems.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
And I know of a CEO who used to either get there first, or let the wannabes struggle over the crumbs. Name of Bill Gates. Quality is primarily a subjective opinion; witness the 90+% of the population of the planet using Windows, despite the occasional Blue Screen of Death, or necessary re-booting orre-installing required. Similarly, whether a product is crap or not is again an opinion, not an objective evaluation that can applied in all cases. The Debian flavor of Linux is considered "the best" by some, and "the worst" by some. The opinions are subjective. Everyone TW wants to believe that he or she is producing quality documentation that creates a warm fuzzy in the user, and makes customers-for-life of the company that produces whatever is being documented. I simply suggest a reality check may be more useful. If the TW is documenting software, perhaps he or she should change fields to one with a slower pace of life (and writing). The option is to accept the realities of the marketplace, and how those influence and constrain the production of technical documentation. In a world in which dynamic onlne help files are rapidly replacing hard copy documents, it seems more useful to focus on developing a skill set that enables high-volume production of acceptable quality content, rather than obsessing over trivial (to most users) details of grammar, construction, or voice. In that direction may lie the future of TW--get it written, get it online, and concentrate on the Pareto principle of satisfying the needs of the majority of users rather than obsessing over the subjective opinions of the minority. < From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > ...or similar biggies realize that time-to-market is everything, > > Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. > > I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wisely fired him and put a new CEO at the helm.> > > -Gillian> > _ Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare! http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hotmailnews___ 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
...or similar biggies realize that time-to-market is everything, Time-to-market is not everything if you sacrifice quality. If you're first on the market but your product is crap, the fact that you were first on the market is irrelevant. I know a CEO who got fired because all he cared about is being first on the market but his products were crap and failed often. Other company's that were slower to market but turned out quality products, stole marketshare from that company. The company almost went under until the board of Directors wisely fired him and put a new CEO at the helm. -Gillian -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Technical Writer Sent: Friday, October 19, 2007 12:35 AM To: framers@lists.frameusers.com Subject: radical revamping of techpubs The "external documentation" recommended for XP and agile development is fundamentally different than the documentation model used in old-style waterfall design. Because the application itself is built in an iterative process, rather than being carved in stone, reacting to feedback from the client, documentation before the last minute is pointless. The reason should be obvious; the application being documented in the early stages bears little resemblance to the application delivered. That is not incompetence on the part of the people footing the bill, nor chicanery on the part of the developer. It is directly related to the reason why online help files are viewed so dimly by the average user; the user doesn't know what to ask to get the answer they need. Similarly, the client may think he, she, or they want ab and d, when what they really need is wx and a little y. Until they see a prototype of ab and d, they may not honestly realize that ab and d is not what they need. There are some developers who attach themselves to large corporations, turn out bloated monstrosities that do very little, and insist that everything be cut-and-dried and filed in triplicate before the first line of code is written. That presupposes that the client knows up front exactly what the final deliverable should be. That is almost never the case. Change is what XP does really well, and in that change, it is pointless to document the app at each iteration, then toss all the carefully crafted prose because it doesn't describe reality now, and only describes what reality used to be. In 2007, software developers other than Microsoft, Oracle, or similar biggies realize that time-to-market is everything, and first mover advantage goes to the swift. Lean management and agile development are attempts to gain a competitive advantage or a bit more market share. There is little point in obsessing over whether or not the end user recognizes symmetry or consistent voice in the documentation when your competitor is outflanking and outrunning you by hiring double your developer staff in Bangalore. There is room for the old-style, Java Dilbert developers, and for those who document their doings. However, a lot of orgs are realizing that the first step in software development is a workable prototype and a good, solid proof-of-concept. Beyond that, they are also realizing that having a competent business analyst watching over the development process is a major advantage; especially if the BA has enough business sense to know when to pull the plug, send the developers and contractors home, and declare the mess as over. Case in point; Inkos. They were trying to implement SAP ERP software, and were $25 million into it before a new IT manager pulled the plug and declared it "inappropriate for Inkos." Along with the documentation that was supposed to tell the IT staff how to use the spiffy new apps. In short, the pie-in-the-sky is often in the eyes of the client declaring "requirements," when they don't know yet exactly what they want. They know generally enough to welcome XP, and a quickie prototype that enables them to understand exactly what they really want and need. Building software is not like building a bridge or skyscraper, and the simplistic similes to building a house without a detailed blueprint are misleading. When you build a house, you are not usually in a race with the contractor down the road to complete and get on the market first or wind up with a major piece of nothing. You can always sell the house at a discount, and recover all or most of your investment. Clients for a software application dragged out over years of development time might find that its value decreases at a faster rate than it is being developed, and by the time it is delivered, it is outmoded, outdated, and pretty much useless. Whether it is well-documented or not is irrelevant. _ Windows Live Hotmail and Microsoft Office Outlook - together at last. Get it now. http://office.microsoft.com/en-us/outlook/HA102225181033.aspx?pid=CL10
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.
Re: radical revamping of techpubs
Chris Borokowski <[EMAIL PROTECTED]> wrote:In my experience, the average software company calls the TW when the product is nearing completion, with completion usually meaning "five minutes before the ship date," and asks them to WTFM. Yes, they do. And that's exactly why so much of the documentation is frustrating for the customer to use. You can't generate technically correct content that is usable and well-planned and free of glaring typos and grammatical errors when you are only given an average of 30 minutes per page of output. (That is not an exaggeration. I can't begin to tell you how many times I've been asked to generate a couple hundred pages of new material in less than a week.) This is the "churn" approach to documentation, and it demonstrates that the company regards documentation as unimportant, an afterthought - and that they have no idea what it takes to generate something worthy of reading rather than using as fireplace kindling. In those situations, the TWs are forced to just do the best they can with what they're given in the alloted time...being quite thankful that their own names are not in the by-line. The smaller percentage of companies that do involve documentation earlier in the process and actually solicit feedback from their customer base and then communicate that feedback in meaningful ways to the product team (including writers) are the ones who end up with better overall customer satisfaction and better accompanying/supporting documentation, be it online or print format. Rene ___ 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
Bill's perception is quite correct, and I'm glad to see other agree. The best TWs I know are the ones who happily roll up their sleeves, dive into an unknown situation and get dirty. My mental image is of them parachuting from a plane far above the unknown, getting last minute shouted orders from a drill seargeant, then grabbing their laptops and parachutes and jumping. It's a lot like journalism (the first love in writing of many of us). You have no idea what the situation is. Someone will hand you a press release that tells you what one fraction of the equation wants you to think. You must dig, find the truth of how the situation functions, and put that down in the kind of description you'd use for a complex design. Right now, there's a massive convergence in technology because it all uses the same basic interface elements. Web2.0 software is all server based, but Web3.0 may be cloud-based, and in both cases, the basics of the interface, networking and remote software interface are well known. The old TW job would have been to describe these. The new one is to give the users power over the application and show them how to become power users. In other words, people are now familiar with the basics of the task, so we have to show them a power user method that quickly gets them up and running and dominating their most likely tasks. What we're doing now is what aftermarket books did in the 1980s and 1990s. In my view, technical writers should recognize that unless we adapt, we're going to become specialized contractors called in when the real work is done to write the manual (WTFM) and then skedaddle. What we could be doing instead is throughout the life of the product, studying how it interfaces with the user and making that process more facile. In this new role, we'd be part journalist, part communicator, part trainer, part project manager, and part interaction designer and user advocate. This is to the benefit of writers, as we get to spend the entire product development cycle getting to know it and get a more justifiably necessary and lasting role, and companies, as they get several roles in one. --- Rene Stephenson <[EMAIL PROTECTED]> wrote: > 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?" > > 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.
Re: radical revamping of techpubs
I'm somewhat thankful they did, as the result was a standardization of hardware that allows $500 to buy a better quality machine than a $1500 Macintosh or $2500 custom UNIX. Sometimes aggression in business can produce very fortunate results for us little people. --- Ron Miller <[EMAIL PROTECTED]> wrote: > In my view, the only reason Windows has dominated personal computing > is because Microsoft bullied hardware company into selling its > products. It told computer manufacturers throughout the 90s when it > built its domination to either use only Windows or to have to pay > more for each copy if they didn't. 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.
RE: radical revamping of techpubs
>From my experience, HTML-encoded email seems to screw up more than it helps. Stick to good ol 7-bit ASCII. --- John Hedtke <[EMAIL PROTECTED]> wrote: > Actually, no, that's not the case, Gillian; Tekwryter's emails > directly to me have been well-formatted. I think this is more an > effect of the listserve software doing something unexpected. 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.
RE: radical revamping of techpubs
Yes. I'm a Eudora user for the last 12 years and I tend to eschew HTML mail. At 07:10 AM 10/22/2007, Chris Borokowski wrote: From my experience, HTML-encoded email seems to screw up more than it helps. Stick to good ol 7-bit ASCII. --- John Hedtke <[EMAIL PROTECTED]> wrote: > Actually, no, that's not the case, Gillian; Tekwryter's emails > directly to me have been well-formatted. I think this is more an > effect of the listserve software doing something unexpected. 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/john%40hedtke.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. Yours truly, John Hedtke Author/Consultant/Contract Writer www.hedtke.com <-- website Region 7 Director, STC 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
Technical Writer wrote: > but otherwise not particularly useful." To believe that a > secondary industry is necessary to assure an acceptable level > of quality in production is impoverished. Quality goods can > be produced by motivated, competent workers without a QA overseer. And later: > Yes. It is mandatory that conscientious performance of a > particular work task include--at a minimum--an acceptable > level of quality. Without the intervention of the QA > department. The Theory X management view that people are > lazy, don't care about quality, and will do everything > possible to avoid work unless micromanaged every moment is > obsolete, and indicative of little more than a failure of > management. This is a remarkably uninformed view of what quality is and what Quality Assurance does. It's been two generations since the work of Deming. Anyone who still thinks that quality is purely subjective, that all you need to assure quality is conscientious, motivated workers, and that the QA department is a bunch of "overseers" whipping workers into line, clearly needs to learn something about the subject before opining about it. I'll skip the rest of Technical Writer's posts until the poor quality of the formatting improves. 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.
re: radical revamping of techpubs
Sorry, but I find the thread both: a) Off-topic b) Misleading. Iterative sofware methods require iterative documentation methods, but by no means do they eliminate the parallel need for early draft user manuals. In fact, Steve McConnell (Code Complete) proposes early draft user guides as an agile replacement for requirements specs. Ben > Because the application itself is built in an iterative process, rather than > being carved in stone, reacting to feedback from the client, documentation > before the last minute is pointless. The reason should be obvious; the > application being documented in the early stages bears little resemblance > to the application delivered. Ben HechterVancouver [EMAIL PROTECTED] ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
Well, a difference of opinion is what makes a horse race. Iterative software methods do not require iterative documentation methods; in most cases, documentation before the last iteration is considered both wasteful and useless. While I have a great deal of respect for Steve McConnell, proposing early draft user guides as a replacement for requirement specs is a bit off the road. If you develop software, and intend to use early draft user guides instead of requirements, you are going to be greeting the folks at Wal-Mart rather than trying to pull back a contract or two from Bangalore. The statement is at odds with most developers' (and most business analysts') understanding of "requirements." Putting an occasional "agile" into a sentence doesn't make the process any more reasonable. I didn't invent the idea of ignoring documentation until the final product is ready (or almost ready) to ship. Far more intelligent, competent, and capable people than me have decided that "involving TWs from the early stages of development" is only useful when the end product is carved in stone before the first line of code is written. That, for better of worse, is rarely the case. Lastly, given that about a third of all software projects, agile or otherwise, fail so badly they are abandoned, if you ignore documentation completely, you have a one in three chance of coming out ahead when the project flops because you have at least saved the cost of documentation. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Sun, 28 Oct 2007 12:21:17 -0700From: [EMAIL PROTECTED]: re: radical revamping of techpubsTo: [EMAIL PROTECTED]: [EMAIL PROTECTED], but I find the thread both:a) Off-topicb) Misleading. Iterative sofware methods require iterative documentation methods, but by no means do they eliminate the parallel need for early draft user manuals. In fact, Steve McConnell (Code Complete) proposes early draft user guides as an agile replacement for requirements specs.Ben> Because the application itself is built in an iterative process, rather than > being carved in stone, reacting to feedback from the client, documentation > before the last minute is pointless. The reason should be obvious; the > application being documented in the early stages bears little resemblance > to the application delivered. Ben Hechter Vancouver BC [EMAIL PROTECTED] _ Windows Live Hotmail and Microsoft Office Outlook – together at last. Get it now. http://office.microsoft.com/en-us/outlook/HA102225181033.aspx?pid=CL100626971033___ 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
I belong to several message - interest groups and I am used to hearing people give their opinions in a bombastic manner. So its no big deal to see that happening here. But if this discussion is to have any real value it will be to share our perspectives with others and learn something about points of view's entirely different than our own, which requires some tolerance and mutual respect. My view and experience is that it definitely helps to get the TW involved early on, but its a waste of time for them to sit all the way through each meeting, and for the entire duration of each meeting. Marketing requirements documents and engineering specification documents, if they are adequately written will help the TW formulate the user documentation at a fairly early stage, but the bulk of the documentation effort comes towards the end of the development cycle. And ideally the writer of the user guide if that is they type of documentation we are discussing now, should be a knowledgeable user with some fresh insights into the learning curve the novice user will face, and some empathy for that new user. Ignoring the need for documentation, putting it off until the last moment is a formula for poor quality documentation. - In my humble opinion. Have a great work week! Leslie -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Technical Writer Sent: Sunday, October 28, 2007 5:47 PM To: [EMAIL PROTECTED]; framers@lists.frameusers.com Subject: RE: radical revamping of techpubs Well, a difference of opinion is what makes a horse race. Iterative software methods do not require iterative documentation methods; in most cases, documentation before the last iteration is considered both wasteful and useless. While I have a great deal of respect for Steve McConnell, proposing early draft user guides as a replacement for requirement specs is a bit off the road. If you develop software, and intend to use early draft user guides instead of requirements, you are going to be greeting the folks at Wal-Mart rather than trying to pull back a contract or two from Bangalore. The statement is at odds with most developers' (and most business analysts') understanding of "requirements." Putting an occasional "agile" into a sentence doesn't make the process any more reasonable. I didn't invent the idea of ignoring documentation until the final product is ready (or almost ready) to ship. Far more intelligent, competent, and capable people than me have decided that "involving TWs from the early stages of development" is only useful when the end product is carved in stone before the first line of code is written. That, for better of worse, is rarely the case. Lastly, given that about a third of all software projects, agile or otherwise, fail so badly they are abandoned, if you ignore documentation completely, you have a one in three chance of coming out ahead when the project flops because you have at least saved the cost of documentation. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Sun, 28 Oct 2007 12:21:17 -0700From: [EMAIL PROTECTED]: re: radical revamping of techpubsTo: [EMAIL PROTECTED]: [EMAIL PROTECTED], but I find the thread both:a) Off-topicb) Misleading. Iterative sofware methods require iterative documentation methods, but by no means do they eliminate the parallel need for early draft user manuals. In fact, Steve McConnell (Code Complete) proposes early draft user guides as an agile replacement for requirements specs.Ben> Because the application itself is built in an iterative process, rather than > being carved in stone, reacting to feedback from the client, documentation > before the last minute is pointless. The reason should be obvious; the > application being documented in the early stages bears little resemblance > to the application delivered. Ben Hechter Vancouver BC [EMAIL PROTECTED] _ Windows Live Hotmail and Microsoft Office Outlook together at last. Get it now. http://office.microsoft.com/en-us/outlook/HA102225181033.aspx?pid=CL100626971033___ 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/lhs_emf%40pacbell.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.com/mailman/opt
RE: radical revamping of techpubs
I agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - interest groups and I am used to hearing people give their opinions in a bombastic manner. So its no> big deal to see that happening here. But if this discussion is to have any real value it will be to share our perspectives with> others and learn something about points of view's entirely different than our own, which requires some tolerance and mutual respect.> > > My view and experience is that it definitely helps to get the TW involved early on, but it’s a waste of time for them to sit all the> way through each meeting, and for the entire duration of each meeting.> > Marketing requirements documents and engineering specification documents, if they are adequately written will help the TW formulate> the user documentation at a fairly early stage, but the bulk of the documentation effort comes towards the end of the development> cycle. And ideally the writer of the user guide if that is they type of documentation we are discussing now, should be a> knowledgeable user with some fresh insights into the learning curve the novice user will face, and some empathy for that new user.> > Ignoring the need for documentation, putting it off until the last moment is a formula for poor quality documentation.> > - In my humble opinion.> > Have a great work week!> > Leslie> > > -Original Message-> From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On> Behalf Of Technical Writer> Sent: Sunday, October 28, 2007 5:47 PM> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> > > Well, a difference of opinion is what makes a horse race. Iterative software methods do not require iterative documentation methods;> in most cases, documentation before the last iteration is considered both wasteful and useless. While I have a great deal of respect> for Steve McConnell, proposing early draft user guides as a replacement for requirement specs is a bit off the road. > > If you develop software, and intend to use early draft user guides instead of requirements, you are going to be greeting the folks> at Wal-Mart rather than trying to pull back a contract or two from Bangalore. The statement is at odds with most developers' (and> most business analysts') understanding of "requirements." Putting an occasional "agile" into a sentence doesn't make the process any> more reasonable. > > I didn't invent the idea of ignoring documentation until the final product is ready (or almost ready) to ship. Far more intelligent,> competent, and capable people than me have decided that "involving TWs from the early stages of development" is only useful when the> end product is carved in stone before the first line of code is written. That, for better of worse, is rarely the case.> > Lastly, given that about a third of all software projects, agile or otherwise, fail so badly they are abandoned, if you ignore> documentation completely, you have a one in three chance of coming out ahead when the project flops because you have at least saved> the cost of documentation.> http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content -> Enterprise Websites> > > Date: Sun, 28 Oct 2007 12:21:17 -0700From: [EMAIL PROTECTED]: re: radical revamping of techpubsTo: [EMAIL PROTECTED]:> [EMAIL PROTECTED], but I find the thread both:a) Off-topicb) Misleading. Iterative sofware methods require iterative> documentation methods, but by no means do they eliminate the parallel need for early draft user manuals. In fact, Steve McConnell> (Code Complete) proposes early draft user guides as an agile replacement for requirements specs.Ben> Because the application itself> is built in an iterative process, rather than > being carve
Re: radical revamping of techpubs
Actually, I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with. - Original Message From: Technical Writer <[EMAIL PROTECTED]> To: Leslie Schwartz <[EMAIL PROTECTED]>; framers@lists.frameusers.com Sent: Monday, October 29, 2007 8:44:16 AM Subject: RE: radical revamping of techpubs I agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/ Specializing in the Design, Development, and Production of: Technical Documentation - Online Content - Enterprise Websites > From: [EMAIL PROTECTED] > To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com > Subject: RE: radical revamping of techpubs > Date: Sun, 28 Oct 2007 19:04:10 -0500 > > I belong to several message - interest groups and I am used to hearing people > give their opinions in a bombastic manner. So its no > big deal to see that happening here. But if this discussion is to have any > real value it will be to share our perspectives with > others and learn something about points of view's entirely different than our > own, which requires some tolerance and mutual respect. > > > My view and experience is that it definitely helps to get the TW involved > early on, but it’s a waste of time for them to sit all the > way through each meeting, and for the entire duration of each meeting. > > Marketing requirements documents and engineering specification documents, if > they are adequately written will help the TW formulate > the user documentation at a fairly early stage, but the bulk of the > documentation effort comes towards the end of the development > cycle. And ideally the writer of the user guide if that is they type of > documentation we are discussing now, should be a > knowledgeable user with some fresh insights into the learning curve the > novice user will face, and some empathy for that new user. > > Ignoring the need for documentation, putting it off until the last moment is > a formula for poor quality documentation. > > - In my humble opinion. > > Have a great work week! > > Leslie > > > -Original Message- > From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On > Behalf Of Technical Writer > Sent: Sunday, October 28, 2007 5:47 PM > To: [EMAIL PROTECTED]; framers@lists.frameusers.com > Subject: RE: radical revamping of techpubs > > > Well, a difference of opinion is what makes a horse race. Iterative software > methods do not require iterative documentation methods; > in most cases, documentation before the last iteration is considered both > wasteful and useless. While I have a great deal of respect > for Steve McConnell, proposing early draft user guides as a replacement for > requirement specs is a bit off the road. > > If you develop software, and intend to use early draft user guides instead of > requirements, you are going to be greeting the folks > at Wal-Mart rather than trying to pull back a contract or two from Bangalore. > The statement is at odds with most developers' (and > most business analysts') understanding of "requirements." Putting an > occasional "agile" into a sentence doesn't make the process any > more reasonable. > > I didn't invent the idea of ignoring documentation until the final product is > ready (or almost ready) to ship. Far more intelligent, > competent, and capable people than me have decided that "involving TWs from > the early stages of development" is only useful when the > end product is carved in stone before the first line of code is written. > That, for better of worse, is rarely the case. > > Lastly, given that about a third of all software projects, agile or > otherwise, fail so badly they are abandoned, if you ignore > documentation completely, you have a one in three chance of coming out ahead > when the project flops because you have at least saved > the cost of documentation. > http://ww
RE: radical revamping of techpubs
You really hit the nail on the head. Meetings are brain-sapping enough when important information is actually being conveyed, but most people who are on the CC: list for meetings are being given a free hourlong zone-out. Keep the poor TWs out of the unnecessary meetings, or they'll become office shooters. Instead, put them to use in usability (currently dominated by glorified photoshop jockeys in too many places) or another capacity suited to their abilities. --- Leslie Schwartz <[EMAIL PROTECTED]> wrote: > My view and experience is that it definitely helps to get the TW > involved early on, but its a waste of time for them to sit all the > way through each meeting, and for the entire duration of each > meeting. 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.
re: radical revamping of techpubs
I like this idea, a lot. Instead of writing instructions out in a dry abstraction and passive voice, explain how the application should work from a user perspective. What a little gem of an idea. Thanks for posting it. --- Ben Hechter <[EMAIL PROTECTED]> wrote: > In fact, Steve McConnell (Code > Complete) proposes early draft user guides as an agile replacement > for requirements specs. 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.
RE: radical revamping of techpubs
Hi, Chris and Ben, I like it too ... I am going to copy people inside our company on this concept. Z Chris Borokowski Chris Borokowski <[EMAIL PROTECTED]> wrote: > > I like this idea, a lot. > > Instead of writing instructions out in a dry abstraction and passive > voice, explain how the application should work from a user perspective. > > What a little gem of an idea. Thanks for posting it. > > --- Ben Hechter <[EMAIL PROTECTED]> wrote: > > > In fact, Steve McConnell (Code Complete) proposes early draft user guides as an agile replacement for requirements specs. ___ 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
I consider the technical writer to be the ultimate advocate for the user...Kelly. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of [EMAIL PROTECTED] Sent: Monday, October 29, 2007 12:35 PM To: Chris Borokowski; [EMAIL PROTECTED] Cc: framers@lists.frameusers.com Subject: RE: radical revamping of techpubs Hi, Chris and Ben, I like it too ... I am going to copy people inside our company on this concept. Z Chris Borokowski Chris Borokowski <[EMAIL PROTECTED]> wrote: > > I like this idea, a lot. > > Instead of writing instructions out in a dry abstraction and passive > voice, explain how the application should work from a user perspective. > > What a little gem of an idea. Thanks for posting it. > > --- Ben Hechter <[EMAIL PROTECTED]> wrote: > > > In fact, Steve McConnell (Code Complete) proposes early draft user guides as an agile replacement for requirements specs. ___ 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/kmcdaniel%40pavtech. com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: radical revamping of techpubs
In my view, you're quite right. It's why I took on this career. By making users more powerful, we make technology evolve, and eliminate some of the techno-angst in the world. --- Kelly McDaniel <[EMAIL PROTECTED]> wrote: > I consider the technical writer to be the ultimate advocate for the > user. 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.
RE: radical revamping of techpubs
That is a very big if. A full partner participant-stakeholder, or more likely the department manager? It is more likely that the software developers, business analysts, and the project manager are collaborating to get a decent set of requirements down. At that stage, TWs have no place, whether department managers, full partner participant-stakeholders, or something else. When the requirements are determined, and possibly after several iterations, possibly after a prototype is up and running, TWs might be brought in. Even at that stage, it is early, because the GUI crew may not have the interface coded, the developers might not have the functionality carved in stone, and everything is still uncertain (in regards to exactly what the final product will be and do). TWs complete a very necessary task; creating user assistance. Until the final iteration, until all the requirements have been met, until there is little or no possibility of changes to the end product, there is little point in generating documentation that might become obsolete at the next iteration. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Mon, 29 Oct 2007 08:26:46 -0700From: [EMAIL PROTECTED]: Re: radical revamping of techpubsTo: [EMAIL PROTECTED]: framers@lists.frameusers.com Actually, I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with. - Original Message From: Technical Writer <[EMAIL PROTECTED]>To: Leslie Schwartz <[EMAIL PROTECTED]>; [EMAIL PROTECTED]: Monday, October 29, 2007 8:44:16 AMSubject: RE: radical revamping of techpubs I agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - interest groups and I am used to hearing people give their opinions in a bombastic manner. So its no> big deal to see that happening here. But if this discussion is to have any real value it will be to share our perspectives with> others and learn something about points of view's entirely different than our own, which requires some tolerance and mutual respect.> > > My view and experience is that it definitely helps to get the TW involved early on, but it’s a waste of time for them to sit all the> way through each meeting, and for the entire duration of each meeting.> > Marketing requirements documents and engineering specification documents, if they are adequately written will help the TW formulate> the user documentation at a fairly early stage, but the bulk of the documentation effort comes towards the end of the development> cycle. And ideally the writer of the user guide if that is they type of documentation we are discussing now, should be a> knowledgeable user with some fresh insights into the learning curve the novice user will face, and some empathy for that new user.> > Ignoring the need for documentation, putting it off until the last moment is a formula for poor quality documentation.> > - In my humble opinion.> > Have a great work week!> > Leslie> > > -Original Message-> From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On> Behalf Of Technical Writer> Sent: Sunday, October 28, 2007 5:47 PM> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> > > Well, a difference of opinion is what makes a horse race. Iterative software methods do not require iterative documentation methods;> in most cases, documentation before the last iteration is considered both wasteful and useless. While I have a great deal of respect> for Steve McConnell, proposing early draft user guides as a replacement for requirement spec
RE: radical revamping of techpubs
I previously worked at a company where the tech writer, in collaboration with development, was responsible for designing and writing the RS and the FS. The docs were highly detailed (about 3000 printed pages per year for a single writer), and were used to not only output and update specifications, but also online help and QA test cases--from a single source. It was initially difficult to maintain and design, but the beauty of it was that any change went through the tw, since all levels in the process were absolutely dependent on it. The writer never missed a trick. Following a single rigid methodology is like being stuck in a box. There is no single process that anyone should absolutely follow--we should constantly strive for new ideas if the results support them. S. Pollock Siemens PLM Software > From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> > Date: Mon, 29 Oct 2007 21:29:15 -0400> CC: > Subject: RE: radical revamping > of techpubs> > > That is a very big if. A full partner > participant-stakeholder, or more likely the department manager? It is more > likely that the software developers, business analysts, and the project > manager are collaborating to get a decent set of requirements down. At that > stage, TWs have no place, whether department managers, full partner > participant-stakeholders, or something else.> > When the requirements are > determined, and possibly after several iterations, possibly after a prototype > is up and running, TWs might be brought in. Even at that stage, it is early, > because the GUI crew may not have the interface coded, the developers might > not have the functionality carved in stone, and everything is still uncertain > (in regards to exactly what the final product will be and do).> > TWs > complete a very necessary task; creating user assistance. Until the final > iteration, until all the requirements have been met, until there is little or > no possibility of changes to the end product, there is little point in > generating documentation that might become obsolete at the next iteration.> > > http://www.tekwrytrs.com/Specializing in the Design, Development, and > Production of:Technical Documentation - Online Content - Enterprise Websites> > > > Date: Mon, 29 Oct 2007 08:26:46 -0700From: [EMAIL PROTECTED]: Re: radical > revamping of techpubsTo: [EMAIL PROTECTED]: framers@lists.frameusers.com> > > > > > Actually, I disagee, if the TW is a full partner participant - > stakeholder, or more likely the department manager in the scenario you are > discussing, they should also participate early on to get the sense of the > uncertainty and what those issues are, at the very least these issues are > going to affect their scheduling and the expectations they have to deal > with.> - Original Message From: Technical Writer <[EMAIL > PROTECTED]>To: Leslie Schwartz <[EMAIL PROTECTED]>; [EMAIL PROTECTED]: > Monday, October 29, 2007 8:44:16 AMSubject: RE: radical revamping of > techpubs> > I agree wholeheartedly. That is not the issue. The issue goes > back to the BA interpretation of (and translation of) the software > requirements. If there is a high level of certainty on the client side about > what the finished product should be, TWs should start early. If not, and it > is essentially a fishing expedition with ambiguous outcome, TWs are only > useful at the last. Unfortunately, the "agile" methodologies strongly sell > the sense of control to executives, pushing the idea that they can develop on > the fly, adding and removing "requirements" as the executives see fit. > http://www.tekwrytrs.com/Specializing in the Design, Development, and > Production of:Technical Documentation - Online Content - Enterprise Websites> > From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; > framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> > Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - > interest groups and I am used to hearing people give their opinions in a > bombastic manner. So its no> big deal to see that happening here. But if this > discussion is to have any real value it will be to share our perspectives > with> others and learn something about points of view's entirely different > than our own, which requires some tolerance and mutual respect.> > > My view > and experience is that it definitely helps to get the TW involved early on, > but it’s a waste of time for them to sit all the> way through each meeting, > and for the entire duration of each meeting.> > Marketing requirements > documents and engineering specification d
RE: radical revamping of techpubs
This may be your experience, in my experience in fact there is no IF about it, I just put it that way to be gentile. Our documents pre-sage multi-mullion dollar contracts (at each stage of the project) and there is always plenty of fuzzy concepts to go around at the early stages. No documents, no contracts. TWs and in particular the directors, managers are involved at these stages. Documentation is a 100% necessary adjunct to business development from the outset. From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Monday, October 29, 2007 8:29 PM To: Leslie H Schwartz; framers@lists.frameusers.com Subject: RE: radical revamping of techpubs That is a very big if. A full partner participant-stakeholder, or more likely the department manager? It is more likely that the software developers, business analysts, and the project manager are collaborating to get a decent set of requirements down. At that stage, TWs have no place, whether department managers, full partner participant-stakeholders, or something else. When the requirements are determined, and possibly after several iterations, possibly after a prototype is up and running, TWs might be brought in. Even at that stage, it is early, because the GUI crew may not have the interface coded, the developers might not have the functionality carved in stone, and everything is still uncertain (in regards to exactly what the final product will be and do). TWs complete a very necessary task; creating user assistance. Until the final iteration, until all the requirements have been met, until there is little or no possibility of changes to the end product, there is little point in generating documentation that might become obsolete at the next iteration. http://www.tekwrytrs.com/ Specializing in the Design, Development, and Production of: Technical Documentation - Online Content - Enterprise Websites _ Date: Mon, 29 Oct 2007 08:26:46 -0700 From: [EMAIL PROTECTED] Subject: Re: radical revamping of techpubs To: [EMAIL PROTECTED] CC: framers@lists.frameusers.com Actually, I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with. - Original Message From: Technical Writer <[EMAIL PROTECTED]> To: Leslie Schwartz <[EMAIL PROTECTED]>; framers@lists.frameusers.com Sent: Monday, October 29, 2007 8:44:16 AM Subject: RE: radical revamping of techpubs I agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/ Specializing in the Design, Development, and Production of: Technical Documentation - Online Content - Enterprise Websites > From: [EMAIL PROTECTED] > To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com > Subject: RE: radical revamping of techpubs > Date: Sun, 28 Oct 2007 19:04:10 -0500 > > I belong to several message - interest groups and I am used to hearing people > give their opinions in a bombastic manner. So its no > big deal to see that happening here. But if this discussion is to have any > real value it will be to share our perspectives with > others and learn something about points of view's entirely different than our > own, which requires some tolerance and mutual respect. > > > My view and experience is that it definitely helps to get the TW involved > early on, but it's a waste of time for them to sit all the > way through each meeting, and for the entire duration of each meeting. > > Marketing requirements documents and engineering specification documents, if > they are adequately written will help the TW formulate > the user documentation at a fairly early stage, but the bulk of the > documentation effort comes towards the end of the development > cycle. And ideally the writer of the user guide if that is they type of > documentation we are discussing now, should be a > knowledgeable user with some fresh insights into the learning curve the > novice user will face, and some empathy for that new user. > > Ignoring the need for documentation, putting it off until the last moment is > a formula for p
RE: radical revamping of techpubs
TW dept managers or directors in particular do have a place in developmental stages. They provide user advocacy in the initial stages, when the development is most nebulous, providing direction and focus toward the common goal of the team: happy customers who like the product and want to buy more. From the TW perspective, the TW mgr/dir gathers info about headcount impact, resource allocation dynamics, etc. You simply cannot categorically state that TWs have no place at any point in a project, because there are too many successful use cases that prove to the contrary, at least 3 of my previous gigs being examples thereof. It depends on the pace of development and the length of the product life cycle, among other things. The faster the products develop and the shorter the product life cycle is, the more critical it is to have TW integration at the earliest phase. Creating user assistance is indeed a necessary task, but it is only one of many that TWs perform. User advocacy getting the user expectations back up the chain into the ears of those who can impact what the users end up getting is at least as important as the more common task of user assistance. If all the user needs is assistance, they'll just ring off the hook with tech support or customer service. User advocacy ensures higher quality products that lower call volume to tech support and customer service. Writing good, usable Help in terms that the user understands is another way to drop the call volume. But, rely on either without the other and you don't reap the maximum benefit of TW staff. Rene Stephenson Technical Writer <[EMAIL PROTECTED]> wrote: That is a very big if. A full partner participant-stakeholder, or more likely the department manager? It is more likely that the software developers, business analysts, and the project manager are collaborating to get a decent set of requirements down. At that stage, TWs have no place, whether department managers, full partner participant-stakeholders, or something else. When the requirements are determined, and possibly after several iterations, possibly after a prototype is up and running, TWs might be brought in. Even at that stage, it is early, because the GUI crew may not have the interface coded, the developers might not have the functionality carved in stone, and everything is still uncertain (in regards to exactly what the final product will be and do). TWs complete a very necessary task; creating user assistance. Until the final iteration, until all the requirements have been met, until there is little or no possibility of changes to the end product, there is little point in generating documentation that might become obsolete at the next iteration. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Mon, 29 Oct 2007 08:26:46 -0700From: [EMAIL PROTECTED]: Re: radical revamping of techpubsTo: [EMAIL PROTECTED]: framers@lists.frameusers.com Actually, I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with. - Original Message From: Technical Writer To: Leslie Schwartz ; [EMAIL PROTECTED]: Monday, October 29, 2007 8:44:16 AMSubject: RE: radical revamping of techpubs I agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - interest groups and I am used to hearing people give their opinions in a bombastic manner. So its no> big deal to see that happening here. But if this discussion is to have any real value it will be to share our perspectives with> others and learn something about points of view's entirely different than our own, which requires some tolerance and mutual respec
RE: radical revamping of techpubs
One workable solution is to let the TW teleconference into the meeting, regardless of whether the TW is in cubicle or offsite. Then, the TW can keep their end on mute and listen for useful tidbits while making use of the time most effectively. That has worked very well for me at several companies, including my current one. If for whatever reason I have to be IN the conference room for a meeting that I know will only be partially relevant, I take my laptop along, sit at an angle to the rest of the group, have one window open for notetaking, and work in FM in a pane beside my notetaking window. My 2¢ Rene Stephenson Chris Borokowski <[EMAIL PROTECTED]> wrote: You really hit the nail on the head. Meetings are brain-sapping enough when important information is actually being conveyed, but most people who are on the CC: list for meetings are being given a free hourlong zone-out. Keep the poor TWs out of the unnecessary meetings, or they'll become office shooters. Instead, put them to use in usability (currently dominated by glorified photoshop jockeys in too many places) or another capacity suited to their abilities. --- Leslie Schwartz wrote: > My view and experience is that it definitely helps to get the TW > involved early on, but its a waste of time for them to sit all the > way through each meeting, and for the entire duration of each > meeting. 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/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.
RE: radical revamping of techpubs
The experience of one person, or even a handful, do not in any way negate an obvious and growing trend in the software industry--directly related to "agile" development--to consider TW involvement as pointless until the final iteration. Yes, there are organizations that still do business as they did 20 or 30 years ago, just as there are still organizations using COBOL, SNOBOL, and other odd applications. If their system works, more power to them, and to the TWs they employ. The difference is in whether or not the organization is developing software, or creating an application that "implements the vision" of a handful of movers and shakers at the top. That handful can do as they please, whether or not it is of long-term benefit to the organization. For software developed in a competitive marketplace, the role of the TW is rapidly changing to a diminished involvement. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites From: [EMAIL PROTECTED]: [EMAIL PROTECTED]; [EMAIL PROTECTED]: RE: radical revamping of techpubsDate: Mon, 29 Oct 2007 21:14:18 -0500 This may be your experience, in my experience in fact there is no IF about it, I just put it that way to be gentile. Our documents pre-sage multi-mullion dollar contracts (at each stage of the project) and there is always plenty of fuzzy concepts to go around at the early stages. No documents, no contracts. TWs and in particular the directors, managers are involved at these stages. Documentation is a 100% necessary adjunct to business development from the outset. From: Technical Writer [mailto:[EMAIL PROTECTED] Sent: Monday, October 29, 2007 8:29 PMTo: Leslie H Schwartz; [EMAIL PROTECTED]: RE: radical revamping of techpubs That is a very big if. A full partner participant-stakeholder, or more likely the department manager? It is more likely that the software developers, business analysts, and the project manager are collaborating to get a decent set of requirements down. At that stage, TWs have no place, whether department managers, full partner participant-stakeholders, or something else. When the requirements are determined, and possibly after several iterations, possibly after a prototype is up and running, TWs might be brought in. Even at that stage, it is early, because the GUI crew may not have the interface coded, the developers might not have the functionality carved in stone, and everything is still uncertain (in regards to exactly what the final product will be and do). TWs complete a very necessary task; creating user assistance. Until the final iteration, until all the requirements have been met, until there is little or no possibility of changes to the end product, there is little point in generating documentation that might become obsolete at the next iteration. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Mon, 29 Oct 2007 08:26:46 -0700From: [EMAIL PROTECTED]: Re: radical revamping of techpubsTo: [EMAIL PROTECTED]: framers@lists.frameusers.com Actually, I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with. - Original Message From: Technical Writer <[EMAIL PROTECTED]>To: Leslie Schwartz <[EMAIL PROTECTED]>; [EMAIL PROTECTED]: Monday, October 29, 2007 8:44:16 AMSubject: RE: radical revamping of techpubsI agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - interest groups and I am used to hearing people give their opinions in a bombastic manner. So its no> big deal to see that happening here. But if this discussion is to h
RE: radical revamping of techpubs
esDate: Mon, 29 Oct 2007 08:26:46 -0700From: [EMAIL PROTECTED]: Re: radical revamping of techpubsTo: [EMAIL PROTECTED]: [EMAIL PROTECTED], I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with.- Original Message From: Technical Writer To: Leslie Schwartz ; [EMAIL PROTECTED]: Monday, October 29, 2007 8:44:16 AMSubject: RE: radical revamping of techpubsI agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - interest groups and I am used to hearing people give their opinions in a bombastic manner. So its no> big deal to see that happening here. But if this discussion is to have any real value it will be to share our perspectives with> others and learn something about points of view's entirely different than our own, which requires some tolerance and mutual respect.> > > My view and experience is that it definitely helps to get the TW involved early on, but it’s a waste of time for them to sit all the> way through each meeting, and for the entire duration of each meeting.> > Marketing requirements documents and engineering specification documents, if they are adequately written will help the TW formulate> the user documentation at a fairly early stage, but the bulk of the documentation effort comes towards the end of the development> cycle. And ideally the writer of the user guide if that is they type of documentation we are discussing now, should be a> knowledgeable user with some fresh insights into the learning curve the novice user will face, and some empathy for that new user.> > Ignoring the need for documentation, putting it off until the last moment is a formula for poor quality documentation.> > - In my humble opinion.> > Have a great work week!> > Leslie> > > -Original Message-> From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On> Behalf Of Technical Writer> Sent: Sunday, October 28, 2007 5:47 PM> To: [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> > > Well, a difference of opinion is what makes a horse race. Iterative software methods do not require iterative documentation methods;> in most cases, documentation before the last iteration is considered both wasteful and useless. While I have a great deal of respect> for Steve McConnell, proposing early draft user guides as a replacement for requirement specs is a bit off the road. > > If you develop software, and intend to use early draft user guides instead of requirements, you are going to be greeting the folks> at Wal-Mart rather than trying to pull back a contract or two from Bangalore. The statement is at odds with most developers' (and> most business analysts') understanding of "requirements." Putting an occasional "agile" into a sentence doesn't make the process any> more reasonable. > > I didn't invent the idea of ignoring documentation until the final product is ready (or almost ready) to ship. Far more intelligent,> competent, and capable people than me have decided that "involving TWs from the early stages of development" is only useful when the> end product is carved in stone before the first line of code is written. That, for better of worse, is rarely the case.> > Lastly, given that about a third of all software projects, agile or otherwise, fail so badly they are abandoned, if you ignore> documentation completely, you have a one in three chance of coming out ahead when the project flops because you have at least saved> the cost of documentation.> http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Tec
RE: radical revamping of techpubs
One role I've found myself in is that of documentation manager, or the person who keeps track of business process, finds what must be organized, and then documents it and finds a sensible hierarchy for those docs, as well as varied delivery methods. It's a fun role. You get to see almost all that goes on, learn a lot, and don't have that unhealthy feeling of waiting around the periphery for an SME to decide to tell you something. They get to know you on a day-to-day basis instead. --- Leslie Schwartz <[EMAIL PROTECTED]> wrote: > TWs and in particular the directors, managers are involved at these > stages. Documentation is a 100% necessary adjunct to business > development from the outset. 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.
RE: radical revamping of techpubs
Luckily, that isn't all they do. Many are employed writing policies and procedures and internal business documentation. Any function that requires explaining concepts understood within a certain skill set that is a minority role in a company is a TW role. Personally, I find it hard to separate the different roles. A well-organized business produces a well-organized product, which can then be easily introduced to the user. If a TW is able to give that feedback during development, and make the product better, the doc gets simpler and bottom line goes up. This is why I see the role of TWs as expanding, not decreasing, in the future. --- Technical Writer <[EMAIL PROTECTED]> wrote: > TWs complete a very necessary task; creating user assistance. Until > the final iteration, until all the requirements have been met, until > there is little or no possibility of changes to the end product, > there is little point in generating documentation that might become > obsolete at the next iteration. 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.
RE: radical revamping of techpubs
For any project that size, won't it take some months for it to complete, as it will for the docs to be done, which means that the TW is first going to be assembling information and writing known parts of the doc, and then expanding to write as parts of the software become formalized? --- Technical Writer <[EMAIL PROTECTED]> wrote: > I said that in an ambiguous, undefined software project > (which many, including multi-million dollar, tend to be), it is > pointless to create documentation of an application that may--and > probably will--change at the next iteration. 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.
RE: radical revamping of techpubs
Enterprise Websites ----------------- Date: Mon, 29 Oct 2007 19:46:00 -0700 From: [EMAIL PROTECTED] Subject: RE: radical revamping of techpubs To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com TW dept managers or directors in particular do have a place in developmental stages. They provide user advocacy in the initial stages, when the development is most nebulous, providing direction and focus toward the common goal of the team: happy customers who like the product and want to buy more. From the TW perspective, the TW mgr/dir gathers info about headcount impact, resource allocation dynamics, etc. You simply cannot categorically state that TWs have no place at any point in a project, because there are too many successful use cases that prove to the contrary, at least 3 of my previous gigs being examples thereof. It depends on the pace of development and the length of the product life cycle, among other things. The faster the products develop and the shorter the product life cycle is, the more critical it is to have TW integration at the earliest phase. Creating user assistance is indeed a necessary task, but it is only one of many that TWs perform. User advocacy getting the user expectations back up the chain into the ears of those who can impact what the users end up getting is at least as important as the more common task of user assistance. If all the user needs is assistance, they'll just ring off the hook with tech support or customer service. User advocacy ensures higher quality products that lower call volume to tech support and customer service. Writing good, usable Help in terms that the user understands is another way to drop the call volume. But, rely on either without the other and you don't reap the maximum benefit of TW staff. Rene Stephenson Technical Writer <[EMAIL PROTECTED]> wrote: That is a very big if. A full partner participant-stakeholder, or more likely the department manager? It is more likely that the software developers, business analysts, and the project manager are collaborating to get a decent set of requirements down. At that stage, TWs have no place, whether department managers, full partner participant-stakeholders, or something else. When the requirements are determined, and possibly after several iterations, possibly after a prototype is up and running, TWs might be brought in. Even at that stage, it is early, because the GUI crew may not have the interface coded, the developers might not have the functionality carved in stone, and everything is still uncertain (in regards to exactly what the final product will be and do). TWs complete a very necessary task; creating user assistance. Until the final iteration, until all the requirements have been met, until there is little or no possibility of changes to the end product, there is little point in generating documentation that might become obsolete at the next iteration. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites Date: Mon, 29 Oct 2007 08:26:46 -0700From: [EMAIL PROTECTED]: Re: radical revamping of techpubsTo: [EMAIL PROTECTED]: framers@lists.frameusers.com Actually, I disagee, if the TW is a full partner participant - stakeholder, or more likely the department manager in the scenario you are discussing, they should also participate early on to get the sense of the uncertainty and what those issues are, at the very least these issues are going to affect their scheduling and the expectations they have to deal with. - Original Message From: Technical Writer To: Leslie Schwartz ; [EMAIL PROTECTED]: Monday, October 29, 2007 8:44:16 AMSubject: RE: radical revamping of techpubs I agree wholeheartedly. That is not the issue. The issue goes back to the BA interpretation of (and translation of) the software requirements. If there is a high level of certainty on the client side about what the finished product should be, TWs should start early. If not, and it is essentially a fishing expedition with ambiguous outcome, TWs are only useful at the last. Unfortunately, the "agile" methodologies strongly sell the sense of control to executives, pushing the idea that they can develop on the fly, adding and removing "requirements" as the executives see fit. http://www.tekwrytrs.com/Specializing in the Design, Development, and Production of:Technical Documentation - Online Content - Enterprise Websites> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; framers@lists.frameusers.com> Subject: RE: radical revamping of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several message - interest groups and I am used to hearing people give their opinions i
RE: radical revamping of techpubs
As users become more technically savvy, they become less dependent on vague manuals and more interested in software with a smooth, intuitive, powerful interface and reliable function. See blog post on this issue: http://user-advocacy.blogspot.com/2007/10/users-replacing-specialists-in-it-and.html --- Rene Stephenson <[EMAIL PROTECTED]> wrote: > The involvement of TW/doc mgr early on is not initially > for writing the doc as muc as it is for user advocacy, sanity checks > of UIS or other specs from a user-driven perspective, as well as > getting buy-in and resource allocation far enough in advance that > creating a remotely usable document is at all feasible. The later > the TW is inserted into the process, the harder it is to create > anything better than basic functionally-driven documents. 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.
RE: radical revamping of techpubs
This is a good idea, and I'll try it. I end up attending most because in my little world, seeing the gestures and facial expressions can tell me a lot, but often most of that knowledge shouldn't go in the docs anyway :) --- Rene Stephenson <[EMAIL PROTECTED]> wrote: > One workable solution is to let the TW teleconference into the > meeting, regardless of whether the TW is in cubicle or offsite. 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.
