res@ihuxn.UUCP (Rich Strebendt) (11/28/84)
In response to a recent comment on the net: | Nope. Microsoft is at least third, since AT&T is in there. My experience | with derivative UN*X documentation (i.e., not straight from AT&T) is that | is much less well typeset and printed (frequently offset reproduction of | daisywheel output), but that its content is always a tiny (note the word well) | improvement on what AT&T shipped. This is not surprising, since there is | only one direction one can go when starting from AT&T documentation. As a person in the AT&T organization responsible for developing the AT&T 3B2 and 3B5 Computers, I am seriously interested in this comment. What I am looking for from the author of the above comment (and from anyone else who has constructive input) are some suggestions that I can pass along, to the people here who are responsible to some extent for the AT&T documentation for the 3B2 and 3B5 Computers, as to how to improve that documentation. It is difficult in written communication to get across the fact that I am sincere in this request and am not being sarcastic or condescending. If you can tell me where your expectations for the contents or the presentation of the material in the documents were not realized, I would like to pass this information along to make the next iteration of the documentation better. I do know that a lot of effort has gone into the design of the documents and into proofreading and error checking the contents. I also realize that nothing is perfect. Please direct constructive criticism to me at the net address or the U. S. Mail address below. Rich Strebendt ...!ihnp4!ihuxn!res AT&T Bell Laboratories Room 2F-426 1100 East Warrenville Road Naperville, IL 60566
lmm@teddy.UUCP (Linda M. McInnis) (11/29/84)
In article <887@ihuxn.UUCP> res@ihuxn.UUCP (Rich Strebendt) writes: >In response to a recent comment on the net: > >| Nope. Microsoft is at least third, since AT&T is in there. My experience >| with derivative UN*X documentation (i.e., not straight from AT&T) is that >| is much less well typeset and printed (frequently offset reproduction of >| daisywheel output), but that its content is always a tiny (note the word well) >| improvement on what AT&T shipped. This is not surprising, since there is >| only one direction one can go when starting from AT&T documentation. > >As a person in the AT&T organization responsible for developing the >AT&T 3B2 and 3B5 Computers, I am seriously interested in this comment. >What I am looking for from the author of the above comment (and from >anyone else who has constructive input) are some suggestions that I >can pass along, to the people here who are responsible to some extent >for the AT&T documentation for the 3B2 and 3B5 Computers, as to how >to improve that documentation. > >It is difficult in written communication to get across the fact that I >am sincere in this request and am not being sarcastic or condescending. >If you can tell me where your expectations for the contents or the >presentation of the material in the documents were not realized, I >would like to pass this information along to make the next iteration of >the documentation better. I do know that a lot of effort has gone into >the design of the documents and into proofreading and error checking >the contents. I also realize that nothing is perfect. > >Please direct constructive criticism to me at the net address or the >U. S. Mail address below. > > Rich Strebendt > ...!ihnp4!ihuxn!res > > AT&T Bell Laboratories > Room 2F-426 > 1100 East Warrenville Road > Naperville, IL 60566 To: genrad!decvax!harpo!whuxlm!whuxl!houxm!ihnp4!ihuxn!res Subject: Re: Quality of AT&T Documentation Newsgroups: net.micro,net.micro.trs-80 In-Reply-To: <887@ihuxn.UUCP> References: <190@ncoast.UUCP> <2374@ucla-cs.ARPA> <243@desint.UUCP> Organization: GenRad, Inc., Concord, Mass. Cc: Bcc: In article <887@ihuxn.UUCP> you write: >In response to a recent comment on the net: > >| Nope. Microsoft is at least third, since AT&T is in there. My experience >| with derivative UN*X documentation (i.e., not straight from AT&T) is that >| is much less well typeset and printed (frequently offset reproduction of >| daisywheel output), but that its content is always a tiny (note the word well) >| improvement on what AT&T shipped. This is not surprising, since there is >| only one direction one can go when starting from AT&T documentation. > >As a person in the AT&T organization responsible for developing the >AT&T 3B2 and 3B5 Computers, I am seriously interested in this comment. >What I am looking for from the author of the above comment (and from >anyone else who has constructive input) are some suggestions that I >can pass along, to the people here who are responsible to some extent >for the AT&T documentation for the 3B2 and 3B5 Computers, as to how >to improve that documentation. > >It is difficult in written communication to get across the fact that I >am sincere in this request and am not being sarcastic or condescending. >If you can tell me where your expectations for the contents or the >presentation of the material in the documents were not realized, I >would like to pass this information along to make the next iteration of >the documentation better. I do know that a lot of effort has gone into >the design of the documents and into proofreading and error checking >the contents. I also realize that nothing is perfect. > >Please direct constructive criticism to me at the net address or the >U. S. Mail address below. > > Rich Strebendt > ...!ihnp4!ihuxn!res > > AT&T Bell Laboratories > Room 2F-426 > 1100 East Warrenville Road > Naperville, IL 60566 ==================================================== I've re-written at least three separate sets of UNIX manuals over my career as a tech. writer. Some of the problems involved are: UNIX manual page sources are never updated!!! Most date from 1979. Corrections for known bugs are never made or included. The instructions for using the manual documentation commands are missing or cryptic. Programmers are nefarious for deleting documentation from the source tapes. Thus you have to begin from scratch or "borrow" source from another UNIX machine. Good Documentation takes time and money. For example, at my last client's company, I was "in charge" of UNIX documentation. NOTHING had been done for 2 years on documentation and I was brought in 3 months before they shipped their product to document UNIX and their hard- ware!!! I wasn't given a list of supported commands until 6 weeks before ship. Since it takes 3-6 weeks to runoff, pasteup, and print a UNIX manual, it didn't leave much time to produce quality documentation. Some suggestions I have are: Plan ahead. Good documentation takes at least 60% as long as the product to develop. Your writers should be assigned to the project as soon as there is a commitment to the product. Write instructions for the tech. writer about the use of the man macro package and what it can and can't do. Include these with the man pages. Generate documentation tools for the programmers. One system I helped develop had a control on placing source code into certain directories that would notify me when a new program was inserted. Another system I worked on used a shell script to prompt for entries and set up the manual page with nroff commands then placed a copy in my to-be-edited directory. Make sure programmers/developers realize that it is part of their responsibility to provide tech. writers with the information necessary to write good documentation. This includes tested examples of the use of every command. Don't sell the documentation short. UNIX is very well documented-unfortunately in about 7000 places. The organization of the manual is one tremendous problem. UNIX documentation was written for gurus not "average" users-many people have been making a bundle of money explaining UNIX to "naive" and average users. I'd suggest you survey the successful UNIX books, buy the rights to a couple, edit them for technical accuracy pertaining to special features of your machine and put them out as introductions under your covers. I'm glad to see that someone does care about documentation of UNIX. I really enjoy working with UNIX and would like to see a good set of manuals come from AT & T. Sorry for the rant, this topic sets me off sometimes. I've worked very hard for about six or seven years to promote the following idea. What do you get when you buy a computer system?? Hardware Software Manuals That tells me that documentation is at least a third of the product. Shouldn't it get at least a third of the resources dedicated to the product development?? And shouldn't the people who write documentation have the same level of credentials and be treated with as much respect as those who generate the code?? If you'd like to chat about this sometime, my phone number is (617) 862-6761. My electronic mail address until the end of December, 1984 is: genrad!teddy!lmm Flames are welcome: I love electronic mail. Linda M. McInnis -- Linda M. McInnis USENET: genrad!teddy!lmm "I used to be disgusted, now I'm just amused."