Re: Executable Documentation to Supplement Data Semantics

Adrian--

Yes, certainly documentation (executable or not) ought to be of higher 
quality than it generally is.  But I still think that more is needed 
than simply executable English (for documentation or not).  For a given 
program, the program itself (the code) and the documentation have 
different purposes, and are intended for different audiences.

*  The audience of the code is the machine, and the code is supposed to 
specify in precise detail what the machine should do under any 
circumstances.

*  The audience of the documentation is a human, and (glossing over that 
there are different levels of documentation for the moment) the 
documentation is supposed to help the human understand what the code 
does, and/or how to use it, NOT to specify all the details that the code 
does.

Now consider the application of executable English.  If the 
documentation is written in executable English, what does executing it 
produce (if you assume that the documentation is not at precise a 
description as the code)?  If, on the other hand, the executable English 
is sufficiently detailed to actually specify the behavior of the 
application itself, will a human be able to comprehend it, even though 
it's in "English"?

Note that this isn't an issue raised by the use of English;  the issue 
involves the level of detail necessary in different kinds of 
descriptions.  The same issue arises in declarative programming 
languages, for programs that do reasonably complicated things.  Just 
because the code is "declarative" doesn't necessarily mean it's easy to 
understand.  To see this same thing happening in English, the next time 
you install a piece of software, read the whole licensing agreement. 
Even to a native English-speaker, it's not always all that clear what 
you're agreeing to (other than that the software provider isn't 
responsible for what happens next).

To end where I began, I don't mean this as a slap at the idea of 
executable English.  But it is a slap at the idea that the mere use of 
an English dialect necessarily deals with all the issues involved in 
communicating semantics.

--Frank

Adrian Walker wrote:
> Hi Frank --
> 
> You wrote...
> 
>> I don't mean this as a slap at the idea of "executable English" per 
>> se, but a bit more is going to be needed than to simply make 
>> "documentation" executable (you did well to put "documentation" in 
>> quotation marks). The idea that anyone could directly execute most of 
>> the "documentation" *I* see is the scariest thing I've heard in a long 
>> time.  Give me a place to find a nice, safe cave somewhere before it 
>> happens, will you? (Or maybe we need monthly "documentation patches"?)
> 
> 
> Yes, there's plenty of non-executable, low quality application program 
> documentation out there.
> 
> Given that the data semantics (in XML or other notations) do not contain 
> enough real world meaning, the existing, non-executable documentation is 
> the only semantic link between what the applications are supposed to do 
> and what they actually do.
> 
> So, if that non-executable documentation is of low quality, then so is 
> the semantic link.  That would seem to strengthen the motivation for 
> _avoiding_ the scenario:
> 
> /
>     1. Someone writes some documentation to supplement the data semantics 
>     2. A team of programmers reads the documentation and writes an
>     application program 
>     3. If we are lucky, the programmers include the documentation as a
>     comment in the program 
>     4. A web service computes over 15 nodes of the net, and produces an
>     answer for a business-level user. 
>     5. The user is uneasy with the answer and asks the help desk for
>     clarification 
>     6.  If the priority is high enough, the help desk asks the programmers 
>     7.  If the programmers are still around, and can remember what they
>     did... 
>     8.  ...
> 
> 
> 
> /
> 
> If, on the other hand, we insist that future documentation should be 
> executable, it can be checked by running it on test cases.  That 
> provides a stronger application-level semantic link to supplement the 
> data semantics.  Once we shift the representation in this way, a system 
> can also provide English explanations of what it is doing.
> 
>                                 Cheers,  -- Adrian
>

Received on Saturday, 5 February 2005 16:53:27 UTC