billwolf%hazel.cs.clemson.edu@hubcap.clemson.edu (William Thomas Wolfe,2847,) (09/03/89)
From markd@salmon.rtech.com (Mark P. Diamond): > if this is my first time using a computer, how do I know that the > power comes from the outlet, and not say the bridge lines, cabling > or other wires? Obvious? My telephone doesn't have an AC plug. [...] An excellent point. Another example: I just came from a laundromat at which I encountered two gentlemen from a foreign country, who had considerable difficulty figuring out how to operate the washers and dryers. Both of them spoke excellent English, and both seemed quite intelligent, but the directions printed on the washer were NOT clear. Their primary problem was that the washer directed them to insert their coins into the slots (not bothering to specify the precise type of coin, of course), and then failed to tell them that they had to push the coin holder in and then pull it back out again. They waited for a while for the washer to start, but to no avail. Whose fault was this? Not the user's... this was totally a result of inadequate user documentation, caused by a failure on the part of the technical writer to identify and describe all relevant actions. Here's another example: automobile owner's manuals frequently specify that one is to change the oil periodically, but manage to avoid any indication of where one is to put the oil in after draining out the old oil. Since there are quite a few caps on the engine, the question of which one to pour the oil into is nontrivial. The failure of the owner's manual would not be fatal if the caps were labeled with letters like "OIL", and indeed letters are placed on practically everything on the engine which indicate obscure part numbers, etc. But there is absolutely NO lettering which is designed to help the user figure out which cap is associated with which fluid!!! Once again... a very poorly documented product. Most software engineers understand completely the need to define variables before using them; why do technical writers not understand the need to define precisely what is to be manipulated and precisely how to go about manipulating it, for each possible user action??? > What I am really arguing against is the arrogance of engineers who can't > design real systems for real people to use, and the arrogance of service > people who believe their time too precious to waste on "stupid" people. > Maybe, just maybe the system you designed Mr. Engineer isn't as easy to use > or install or fix or whatever as you think. Don't pass the buck onto me > for being stupid. Or worse, if I the user haven't mentally put all the > pieces together, if I'm having a bad day and my boss is pushing me to get > this system online and I run into what I think is a problem, and I call you > Mr. Field Sevice Person, don't treat me like an idiot. Help me solve > our problem. Precisely. Bill Wolfe, wtwolfe@hubcap.clemson.edu
rcw@scicom.AlphaCDC.COM (Robert White) (09/09/89)
In article <6376@hubcap.clemson.edu> billwolf%hazel.cs.clemson.edu@hubcap.clemson.edu writes: >From markd@salmon.rtech.com (Mark P. Diamond): > [good story on the faulty washing machine documentation deleted] > > Most software engineers understand completely the need to define > variables before using them; why do technical writers not understand > the need to define precisely what is to be manipulated and precisely > how to go about manipulating it, for each possible user action??? Several reasons. Most companies are unwilling to put what it takes into technical documentation. They hire inexperienced people who may or may not be technically oriented. I think a willingness to "play user" with the product that is to be documented is a prerequisite. You also must be willing to learn everything there is to know about the product. You can't be good at technical writing until you have written some, issued it, interacted with end users, revised it, and issued it again. You also can't write well unless you use the product in a real life situation. That's a problem shared with test data as well. The parameters of the user application must be understood to write decent manuals. > Bill Wolfe, wtwolfe@hubcap.clemson.edu I can't find it right now, but there is a book with a title something like "The Design of Everday Things" containing excellent discussions on the design (or lack thereof) of everything from hot/cold taps to computer software. For example, if taps are arranged vertically, how do you know which is hot and which is not? Highly recommended. I will try to find the author and title if someone else does not beat me to it. Robert White rcw@scicom.alphacdc.com
eugene@eos.UUCP (Eugene Miya) (09/10/89)
In article <1888@scicom.AlphaCDC.COM> rcw@scicom.UUCP (Robert White) writes: >I can't find it right now, but there is a book with a title something >like "The Design of Everday Things" containing excellent discussions >on the design (or lack thereof) of everything from hot/cold taps to >computer software. That's The Psychology of Everyday Things (POET) by Don Norman UCSD (dnorman@ucsd.edu). A moderately pleasant antecodotal book bashing "form over functionality" [my words]. Would be nice if it went further. Another gross generalization from --eugene miya, NASA Ames Research Center, eugene@aurora.arc.nasa.gov resident cynic at the Rock of Ages Home for Retired Hackers: "You trust the `reply' command with all those different mailers out there?" "If my mail does not reach you, please accept my apology." {ncar,decwrl,hplabs,uunet}!ames!eugene Live free or die.
sommar@enea.se (Erland Sommarskog) (09/11/89)
Robert White (rcw@scicom.UUCP) writes: >For example, if taps are arranged vertically, how >do you know which is hot and which is not? I haven't been confronted with vertical tap arrangements, but I have been to places where hot tap was the one to the right. -- Erland Sommarskog - ENEA Data, Stockholm - sommar@enea.se
csg@pyramid.pyramid.com (Carl S. Gutekunst) (09/12/89)
In article <1888@scicom.AlphaCDC.COM> rcw@scicom.UUCP (Robert White) writes: >Most companies are unwilling to put what it takes into technical documen- >tation. True.... >They hire inexperienced people who may or may not be technically oriented. ^^^^^^^^^^^^^^^^^^^^ That's rarely the problem. Far more common is that companies hire writers for their technical expertise, but don't bother to find out whether they know how to *write*. What you end up with is user documentation that looks like it written by an engineer who came late into the project. I can teach someone the technical stuff, if they are willing to learn. But I sure can't teach 'em how to write. Followups to comp.software-eng only. <csg>
jim@mks.UUCP (Jim Gardner) (09/12/89)
[...] Why is so much documentation bad? I have been a technical writer for ten years, have done a lot of freelancing for different companies, and have a few ideas of things that can go wrong. (a) Writers may be hired on the basis of confused criteria. For example, IBM in Toronto had trouble hiring technical writers. Therefore they hired a number of people who had applied for programming jobs, and promised those people they would be allowed to transfer to programming after they built up a little seniority. Clearly, these people didn't want to *be* writers, nor would they have any feeling for the job. How could anyone expect them to put full effort into what they were doing? (We will ignore the question of how qualified any of these people were to write for a living.) (b) Technical writers are frequently supervised by programmers. Programmers often have the innate belief that the features which were hardest to implement must require the most documentation. In many cases, of course, the details of the implementation have nothing to do with what the documentation should say...but try to convince the programmer of that. (c) Companies often have no idea of what they want their documentation to do. When I begin to write any documentation, one of my first questions is, "Who do you think is going to read this?" Software documentation should be aimed at the needs of the user...but many software vendors have no idea of who the user is going to be. There is a vast difference between what a novice wants to see and what an experienced user wants to see, but companies often do not know who their audience is going to be. (d) Production of software tends to dominate production of documentation in the eyes of many companies. For example, the scheduling for distributing a package may be entirely keyed to the readiness of the software, not the documentation; the second that the software is ready, the company wants the package out the door. This means that the documentation must be prepared before the software has been finished (before the testing is finished at any rate). There have been many times that I have found myself documenting features that don't work yet. I am blithely suggesting that the user try certain commands as examples, when *I* can't try those examples to see if they work. I am happy to say that my current employers have more enlightened attitudes to the documentation process. Nevertheless, I've seen how slap-dash some companies are and bush-league documentation never comes as a surprise to me. Jim Gardner, Mortice Kern Systems
mikeh@dell.dell.com (Mike Hammel) (09/13/89)
In article <1596@mks.UUCP> jim@mks.UUCP (Jim Gardner) writes:
[...]
- the door. This means that the documentation must be prepared
- before the software has been finished (before the testing is
---------------------
- finished at any rate). There have been many times that I have
--------
Don't I know it. In previous work I developed test plans and testcase
suites from internal documentation, ie the stuff the designers wrote
themselves. Lately I work more with external documentation, manuals and
such that come from outside vendors. In both cases I've had to work with
incomplete and incorrect information. Try determining how to test
compatibility or functionality when the folks who designed the thing don't
know what its supposed to do! The "dream" scenario for me would be to have
design documents finished before the product gets to the test group, or in
the case of outside vendor materials, have user documents that are up to date
with the version/release that is received for testing. Unfortunately this
seldom happens (at least for me).
No wonder it seems like the test group is always holding up the product. :-)
(We test engineers know better, though.)
Michael J. Hammel
Dell Computer Corp.
rcw@scicom.AlphaCDC.COM (Robert White) (09/15/89)
>In article <1888@scicom.AlphaCDC.COM> I write: ++Most companies are unwilling to put what it takes into technical documen- ++They hire inexperienced people who may or may not be technically oriented. ^^^^^^^^^^^^^^^^^^^^ Carl S. Gutekunst responds: (csg@pyramid.pyramid.com) >That's rarely the problem. Far more common is that companies hire writers for >their technical expertise, but don't bother to find out whether they know how >to *write*. What you end up with is user documentation that looks like it >written by an engineer who came late into the project. > >I can teach someone the technical stuff, if they are willing to learn. But I >sure can't teach 'em how to write. > I think it depends. My background/bias is in mathematical scientific software. One of the major failings of the company I used to work with was that they hired a series of writers who had no background in the science. This is not to say they couldn't understand what the software did, but rather they were unable to communicate with the end user in familiari industry terms. In other words, the writing seemed alien. In the end, I felt so strongly about this that I wrote my own user guides. Good writing is 20% talent and 80% hard work. I still see very few user guides that are clear, concise, useful, and helpful. Even very technical subjects can be explained clearly given enough effort. One technique that seems to be helpful is to write the user guides first. If a product is designed well, then it is straightforward to document. By the same token, flaws in the program design such as excessive awkwardness of some procedure can be corrected early in the design process. I suppose I am suggesting integration of documentation into the overall engineering of a project from its outset. Yours sincerely, Robert White (rcw@scicom.alphacdc.com) in the program design may show early in the process.
jgn@nvuxr.UUCP (Joe Niederberger) (09/20/89)
>(a) Writers may be hired on the basis of confused criteria. For > example, IBM in Toronto had trouble hiring technical writers. I always thought that IBM had the very finest technical writers (do I *need* a smiley here?) For example, I liked this quote so much I had in done in caligraphy and framed: "For the logical parent to physical parent path, the user controls the sequence in which occurances of the real logical child are accessed from their logical parent by defining a virtual logical child segment type as a physical child of the logical parent of the real logical child, and in addition, by defining a sequence field in the virtual logical child." 4.58 IMS/VS System/Application Design Guide Now, whose fault is it that this blurb is nearly indecipherable ? Is it the poor writer, or the IMS guru who coined such memorable terms as "virtual logical child segment type" and "real logical child" ?? I see the same thing happening today where everything is "object this" and "object that." I contend that much of the difficulty in writing coherent technical documentation is the poor choice of terminology, which is generated, not by technical writers, but by the very creators of the technology in question. Joe Niederberger