[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.

> the compiler already throws out string constants if they aren't
> used for anything.

> Guido ... initially against it ... concerned about the loss of
> information in the TeX markup.
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,

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.