From: Markus <markus@...>
Date: 2004-10-15T01:03:30+09:00
Subject: Re: documentation as source

On Wed, 2004-10-13 at 22:59, James Britt wrote:
> Markus wrote:
> 
> > On Tue, 2004-10-12 at 00:44, Niklas Frykholm wrote:
> > 
> >>I've toyed a bit with literate programming, but I'm not really sold on 
> >>the idea. I guess my problem with "documentation as source" (or even 
> >>with "source as documentation", but that is a smaller gripe) is the 
> >>notion that a program only has one "story". Usually, I find that in my 
> >>programs there are many different stories: a story for a beginner user, 
> >>a story for an expert user, a story for someone who wants to extend the 
> >>module, a story for someone who wants to hack it, a story for someone 
> >>who wants to understand and study the technology behind it. And of 
> >>course, there can be stories can be in different languages. Trying to 
> >>put all these stories as well as the source code in the same document 
> >>tends to be confusing, at least for me.
> > 
> > 
> >      *smile*  Wonderfully put.
> 
> Where do all of these different stories go, if not together, such that 
> when the code changes all of the stories are updated as well?

     Most fiction is layered; a novel may contain many short stories,
each of which advances one or more of the plot threads, tells a few
anecdotes, and may or may not be part of a larger series of related
stories which serve to tie the whole together but do not "advance." 
There are also subtler dependencies that may arise, foreshadowing,
parallelism, etc.

     As a consequence, no one can be expected to "understand" a novel
unless they read it cover to cover.

     Software is often as complex, but requiring that people read it
"cover to cover" before they understand it seems unreasonable. 
Therefore it makes sense (as Niklas suggested) to tease apart the
various stories and tell them separately.  Tools to do this--clean
interface design, use of standards (that can be concisely documented by
reference), change logs/CVS, bug tracking system, design philosophy
documents (which also may be incorporated concisely by reference), all
act in the same was--they take some type of information that could have
been included in the source, merged into a novel of sorts, and pull it
out into a separate document.

      This has the downside (as you point out) that when I want to
modify the code I have to also update the change log and perhaps the bug
list, etc. and this is somewhat less convenient when they are in
separate documents, but overall it is far easier (where in the code do
you document a bug when all you know are the symptoms?  Do you really
want to embed a draft standard in your code as a comment?...) to keep
things distinct and their relationships more restricted.

      -- Markus