From: dewar@cs.nyu.edu (Robert Dewar)
Subject: Re: 2167A
Date: 26 Sep 1994 09:32:54 -0400
Date: 1994-09-26T09:32:54-04:00 [thread overview]
Message-ID: <366ii6$jds@gnat.cs.nyu.edu> (raw)
In-Reply-To: 940925135303_73672.2025_DHR50-1@CompuServe.COM
The biggest weakness of documentation in my experience occurs when it is
prepared independently from the source code. It is almost inevitable that
in this case the documentation does NOT get properly maintained, and quickly
becomes useless.
That's why I *much* prefer the practice of putting extensive high level
documentation in the source files, and then insisting that they be updated
as the sources are updated.
This is very hard to achieve.
Many projects which appear to have wonderful documentation, as measured
by quantity and surface appearence of the documentation, in fact are in
terrible shape. This is especially true when the existence of the external
documentation persuades people that it is unnecssary to document the
code.
next prev parent reply other threads:[~1994-09-26 13:32 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
1994-09-25 13:53 2167A Ken Garlington
1994-09-26 4:35 ` 2167A Rod Cheshire
1994-09-26 13:32 ` Robert Dewar [this message]
-- strict thread matches above, loose matches on Subject: below --
1994-09-30 1:29 2167A Ken Garlington
replies disabled
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox