Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!uwm.edu!rpi!zaphod.mps.ohio-state.edu!lavaca.uh.edu!menudo.uh.edu!starsoft!david
From: david@starsoft (Dave Lowrey)
Newsgroups: comp.sys.amiga.misc
Subject: Re: Coding in English
Message-ID: <18891225.ARN2603@starsoft>
Date: 17 Jan 91 13:24:21 GMT
References: <17.278EA88A@weyr.FIDONET.ORG> <669@caslon.cs.arizona.edu> <747@cbmger.UUCP>
 <8179@ucdavis.ucdavis.edu>
Reply-To: david@starsoft
Followup-To: comp.sys.amiga.misc
Organization: Starbound Software Group
Lines: 52
Expires:
Keywords:
Distribution:

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