david@starsoft (Dave Lowrey) (01/17/91)
In article <8179@ucdavis.ucdavis.edu>, Dan Zerkle writes: > In article <747@cbmger.UUCP> peterk@cbmger.UUCP (Peter Kittel GERMANY) writes: > >In article <669@caslon.cs.arizona.edu> dave@cs.arizona.edu (Dave P. Schaumann) writes: > >> > >>That programmers cannot write in English is already a well known fact. See > >>virtually any Unix documentation if you disagree. > > > >That is very hard news for me. Every day I read carefully all this > >stuff on the net and try hard to adapt to the Speak here, because > >I thought this would be true English. And now you are going to tell > >me that I perhaps learn something not perfect??? > > > >Best regards, Dr. Peter Kittel // E-Mail to \\ Only my personal opinions... > >Commodore Frankfurt, Germany \X/ {uunet|pyramid|rutgers}!cbmvax!cbmger!peterk > > It's true. As a computer programmer, I use two languages. One for > when I'm talking about computers (computerese) and another when I'm > talking with people who don't know about computers (English). I am > not alone in this. > > This leads to a very serious problem with documenting commercial > software. The people who wrote the programs can not write English > well. The people who can write English well can not understand the > computer programs. This means that the manuals for programs are > either incomprehensible (if the programmers write them) or wrong (if > writers are hired for the manuals). > There is a cardinal rule in software documentation...."Those that wrote the software DO NOT write the documentation!!" It seems, at first, that this is a dumb idea. "If I wrote it, than I am the one that knows the most about it". That is the problem. When you understand the software so well, you can't step out and think like a new user. You make too many assumptions. A "technical writer" should take the finished product, design specs, and notes from the developer, and produce the documentation. The software author(s) should be in the critique (sp?) process, of course, but they should not write the doc. If the author feels the s/he MUST write some documentation, have him/her write a "logic manual" or "tech spec." for it. :-) ---------------------------------------------------------------------------- These words be mine. The company doesn't care, because I am the company! :-) Dave Lowrey | david@starsoft or {uhnix1,lobster}!starsoft!david Starbound Software Group | Houston, TX | "Dare to be stupid!" -- Weird Al Yankovic
xanthian@zorch.SF-Bay.ORG (Kent Paul Dolan) (01/20/91)
zerkle@iris.ucdavis.edu (Dan Zerkle) writes: > This leads to a very serious problem with documenting commercial > software. The people who wrote the programs can not write English > well. The people who can write English well can not understand the > computer programs. This means that the manuals for programs are either > incomprehensible (if the programmers write them) or wrong (if writers > are hired for the manuals). peterk@cbmger.UUCP (Peter Kittel GERMANY) responds: > Just to assure you: This is nothing special for English. Here in > Germany it's the same mess. What annoys me most is that computer > magazines here tend to totally forget about rules of how to write > texts. They even are going to use much of English grammar in German > texts which leads to really horrible results. Worst is with > punctuation rules. They differ heavily from the English ones, but now > more and more German texts appear with commas set after English rules. > Pure horror! > From that you can conclude that they are able to read English > documentation, but then they aren't able to convert this into real > German. So this should be an even worse situation than in English > speaking countries. And in a horrible burst of jingoism (note the followup!) I chip in: When computer programming first spread outside the Anglophon nations, the situation was the same as for the airlines and the ships and other communications needs that were no respectors of national borders; programming was done, and spoken of, and documented, in English, so that we wouldn't be involved in a Babel of diverse languages when porting software. Now, Amiga UUCP-Plus is available, but you'd better know the author's native tongue if you want to read the docs; you can get a great PD TeX, and the docs will show up, someday. You can get Unix lharc, and the docs are almost in English, but they throw in the Japanese ones for those who really want to understand the software. I liked it better when the whole world was busy trying to speak _my_ language. Maybe a little kick-ass war will bring English back to respectability. Probably a smiley should be in there someplace, but I learned German, Latin, and Spanish, and I still want to see the code and docs and even commentary in English, damnit. Kent, the man from xanth. <xanthian@Zorch.SF-Bay.ORG> <xanthian@well.sf.ca.us> -- ONE world requires ONE language. We can't afford to keep giving scholarships to proto-dictators so they can later understand CNN while they rape and pillage.