Re: [Axiom-developer] Literate Programming -- Knuth interview

[daly]

On Sat, 2011-11-19 at 08:42 +0000, Martin Baker wrote:
> Tim,
> 
> One issue that occurred to me on this subject. It seems to me the point of 
> HTML and hypertext is that they are not a linear book. What I like about this 
> is that the reader can start at a high level with a small and concise page 
> but 
> they can drill down to any level of detail they may need. Also there can be 
> different entry points for different types of readers such as end users as 
> well as programmers. It would be good if all these types of 'documentation' 
> could be produced by the same tools and advanced end users could drill down 
> to 
> information originally intended for programmers. Using standard code 
> libraries 
> its probably easier to access HTML user documentation/'help files' from 
> within 
> the program rather than writing custom code like hyperdoc.

I chose HTML as the example case because it is known to everyone.
I much prefer latex but not everyone does.

Axiom has an implementation of an HTML replacement for hyperdoc in
Volume 11. There is still much work to be done.

I believe the split between end users and programmers is artificial
and an artifact of the way we currently develop code.

Consider writing a textbook. You start out writing what you believe will
be the first chapter, diving right into the interesting material. 
Eventually you find that Chapter 1 requires some background material
so you write a new Chapter 1 and your interesting material is now in
Chapter 2. As you continue this process you find that the material
you originally put in Chapter 1 is now somewhere near Chapter 4 because
you found many ideas that needed to be explained before you could really
cover the interesting material. 

Often I will read the first 3 chapters of a textbook, then find another
textbook on the same subject and read those first 3 chapters, and even
a third textbook. By the time I've done that I have a firm grasp on the
background essentials and find that I can make progress on later 
chapters with core material.

We have this belief that programmers have a natural ability to dive
into code that is lacking in other people. We assume that someone who
"speaks" C can just read the program and understand it. In my 
experience this is a bad assumption. Programmers have no way to
guess at a design decision that is not written in words any better
than anyone else. Nor do programmers have a magic mind that allows 
them to look at several hundred "sand files" and derive the big 
ideas of the program. Yet we continue to act as if they do.

My experience with literate programming has led me to expect that I
have to write the "first three chapters" (sections, paragraphs, or
whatever) as general overview. I have to make gradual steps from
ideas to implementation. Done properly I believe anyone can read a
literate program, at least superficially, and especially so for the
first few chapters.

After all, the point of literate programming is to communicate ideas
from one human to another. 

The organization of the material into one or many web pages is not
particularly important. I tend to follow the "book" metaphor as
I tend to read a lot of books. Linear material spread over a lot of
pages simply breaks my "linear mind" and I tend to stop reading after
getting a few pages into the material. However, with a PDF style
book my Kindle or PDF reader keeps my last-read-page bookmark and
I can pick up where I left off. 


> 
> I can see the advantages in putting the literate 'documentation' interleaved 
> in the same file as the code. However there also seem to be a lot of 
> disadvantages such as making the above ideas more difficult?

The key test for literate documentation is the "independence test".
Can you point someone at your literate program, have them go off
somewhere to read it, and then come back with the ability to maintain
and modify it?

When you read the tangle web page did you feel that it needed to be
broken up? I thought it made a reasonably smooth transition from the
ideas to the code details with enough words so you could skip reading
the actual code. The code is just there as icons for humans, like
equations in a math book.

If you feel that interleaving videos, animations, navigation, and any
other tricks improves the "independence test" results then these
techniques should be used. If, however, you are just trying to 
organize the material by some random criteria (e.g. alphabetical
or as trees of logically grouped files) then you are undermining 
the transfer of ideas.

Even today, with all of the hyperlinking tricks available, I still
see my iPad using linear, book-like presentations.

Tim