Mailinglist Archive: opensuse (3337 mails)

< Previous Next >
Re: [opensuse] Documentation required BEFORE release!
  • From: David Wright <david.wright@xxxxxxxxxxxxx>
  • Date: Tue, 25 Apr 2006 12:09:19 +0200
  • Message-id: <200604251209.19881.david.wright@xxxxxxxxxxxxx>
Am Dienstag, 25. April 2006 01:36 schrieb Carlos E. R.:
> The Monday 2006-04-24 at 16:05 +0200, houghi wrote:
> > These are all things you need to decide for yourself. You said that there
> > were programs that lacked documentation. Start there. As you are on
> > dialup, use a package that is available on your distro already.
>
> Impossible. You need the sources, and they are not included, you have to
> downloaded them.

You should write the documentation from the original specifications, not from
the source code, same as writing test harnesses and test scripts. If you
write from the specification, you are documenting what the program *should*
do, which acts as a good double check that the code is doing what *it*
should.

Most of the professional documentors I've worked with wouldn't have a clue
where to start if you gave them source code, but give them an executable to
play with and a RUP, CACI etc. standard specification and they are happy
little bees and will knock up documentation in no time...

Dave
--
"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 >
Follow Ups