[Doc-SIG] Evolution of library documentation
Edward Welbourne
Edward Welbourne <eddy@chaos.org.uk>
Sun, 11 Mar 2001 12:28:50 +0000 (GMT)
> At the Python conference, a small group of us discussed the possibility
> of merging the external and internal documentation; that is, moving
> the library reference into the module source files.
good.
> the compiler already throws out string constants if they aren't
> used for anything.
cool.
> Guido ... initially against it ... concerned about the loss of
> information in the TeX markup.
bah.
OK, so it'll pressure ST* into being a bit richer ... big deal.
> But i still think that getting all the docs together in one place is
> a goal worth at least investigating.
hey, understatement is meant to be a British thing - what're you doing
invading our turf, Ka-Ping ;^?
All programmers know: if the code and the docs disagree, mistrust both.
Those involved in databases know:
if data is duplicated, the copies get out of step with one another.
Corollary: if the code and the docs aren't in the same place, you can't
trust either.
`A goal worth at least investigating' ? Try:
A fundamental omission in most existing software management systems.
I trust IPC9 went well,
Eddy.
--
Experienced software engineers know that perhaps 30% of the cost of a
software product goes into specifying it, 10% into coding, and the
remaining 60% on maintenance. -- Ross Anderson.