Mailinglist Archive: opensuse (3337 mails)

< Previous Next >
Re: [opensuse] Documentation required BEFORE release!
  • From: David Wright <david.wright@xxxxxxxxxxxxx>
  • Date: Tue, 25 Apr 2006 11:54:41 +0200
  • Message-id: <200604251154.41329.david.wright@xxxxxxxxxxxxx>
Am Montag, 24. April 2006 12:45 schrieb Carlos E. R.:
> The Monday 2006-04-24 at 10:57 +0200, Henne Vogelsang wrote:
> > Help yourself. Get off _your_ butt and offer projects to write
> > documentation :)
> I'm collaborating in that respect (doing translations), but it is quite
> difficult to document a program you don't know what it does. Only the
> developpers can do that, I'm afraid. I can polish and expand a write up,
> but the first go has to be done by the developpers.

I used to work for a large consultancy, there the documentation was usually
written by a special team of documentors, they had no programming knowledge,
they took the finished (or sem-finished) programs, played with them and read
the technical documentation and came up with user documentation from their
experience, plus collaboration with the programming team for more technical

Usually developers and programmers are very good at writing specifications and
writing code, but aren't as good at explaining it plain language for the
non-computer literate, they tend to make too many assumptions or talk about
the technicalities of the program and not on the normal use of the program...
Don't get me wrong, some programmers can write good user documentation, but
most haven't had the experience.

"I got to go figure," the tenant said. "We all got to figure. There's some way
to stop this. It's not like lightning or earthquakes. We've got a bad thing
made by men, and by God that's something we can change."
- The Grapes of Wrath, by John Steinbeck

< Previous Next >