From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=-0.8 required=5.0 tests=BAYES_00,INVALID_DATE
	autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,c03e01a669cc28b3
X-Google-Attributes: gid103376,public
X-Google-ArrivalTime: 1994-09-26 15:07:05 PST
Path: 
 bga.com!news.sprintlink.net!howland.reston.ans.net!gatech!swiss.ans.net!cmcl2!thecourier.cims.nyu.edu!thecourier.cims.nyu.edu!nobody
From: dewar@cs.nyu.edu (Robert Dewar)
Newsgroups: comp.lang.ada
Subject: Re: 2167A
Date: 26 Sep 1994 09:32:54 -0400
Organization: Courant Institute of Mathematical Sciences
Message-ID: <366ii6$jds@gnat.cs.nyu.edu>
References: <940925135303_73672.2025_DHR50-1@CompuServe.COM>
NNTP-Posting-Host: gnat.cs.nyu.edu
Date: 1994-09-26T09:32:54-04:00
List-Id: <comp.lang.ada>

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.