Darren New wrote:
> andrel wrote:
>> Look at it as if it is a program. The conclusions are the main routine.
> 
> That's what always killed me about mathematical proofs. They always 
> start with all the details, and finally tell you why you care. :-)

Indeed. Most mathematical proofs are like badly documented code. No 
useful comments. Only documenting *what* the final version does (if at 
all), never tell the reader *why* or *how*.

Actually, a possible reason I came up with the analogy in the first 
place is that it is the inverse of Donald Knuth's 'literate programming' 
quest. Don's concept is that code should be as readable as literature. 
To give examples to the community he published much of his source code 
as books.

> 
> I would clarify by saying the document should also *start* with the 
> conclusion, because people are going to be trying to recreate the 
> structure in their head as they read.
The abstract should serve that purpose. There is at least one 
presentation where I deliberately do not do that. I like to see the 
aha-erlebnis in the audience. If I tell them upfront they probably 
switch of falsely assuming that they won't understand it anyway.
> 
> That's what is killing me about reading the Erlang documentation: there 
> are all sorts of cross-references, and no obvious place to start 
> reading.  I wouldn't be surprised if there are circular references 
> throughout, either.
> 
Note to self: the official Erlang need not be included in the wish list,

Post a reply to this message