Home Original page

reStructured Text - suitable for non-documentation?

Raymond Hettinger vze4rx4y at verizon.net
Wed Jun 4 00:02:55 EDT 2003 
"Michele Simionato" <mis6 at pitt.edu> wrote in message
> Hey, literate programming is great!!
>
> But if it was invented in 1984, why is it so little
> widespread ? I hardly heard about it before today
> (except for Leo, the literate programming editor,
> which however I never tried).

It is still around and has many incarnations such as CWEB,
Leo, etc.  There a few issues limiting its popularity.

One of the core ideas is write a piece of documentation that
is a cross between a well written essay and concrete detail
documentation.  The problem here is that not that many
people write well enough to achieve even the essay and
even fewer can effectively combine that with detail docs.
The writing skills need to augmented by knowledge of
the markup language (usually TeX).  And the writer needs
to know the programming language being used.  And the
programmer needs to be skillful enough to write a program
in disconnected fragments that still makes sense and can
be debugged after re-assembly.

Donald Knuth is one person who has all of these skills
and can apply them all at the same time.  In contrast,
the average Joe is lucky to have even a few of the
skills, much less being able to apply them all at the
same time.  It is rarer still to find teams where all of
the programmers can read and write in a literate style.
As some of the python developers can attest, it takes
a while just to get the LaTeX markup correct.

Even if all of the pieces fall into place, there is still a
sense that it takes a lot of work.  So, eventhough there
is a certain pleasure to writing literate code, it is something
you tend to save for that special program and then find that
most tasks are too mundane to warrant using your heavy gun.

Also, I find that the process of writing literately collides with
the Test Driven Development process.  I'm sure it's possible
to do both at the same time, they just don't seem to fit together
naturally.


> BTW, I have in mind an integration of documentation+test suite,
> not documentation+program (a la Knuth).

+1


Raymond Hettinger
More information about the Python-list mailing list