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

INTERNET BUSINESS LOGIC (R)
www.reengineeringllc.com

Adrian Walker
Reengineering LLC
PO Box 1412
Bristol
CT 06011-1412 USA

Phone: USA 860 583 9677
Cell:    USA  860 830 2085
Fax:    USA  860 314 1029




If a lot of the non-executable documentation that's out there is of low quality, then the link


At 03:53 PM 2/4/2005 -0500, you wrote:

Adrian Walker wrote:
snip
The point of the story is that "data semantics" needs to be supplemented with "application semantics".  One way to do this is to ensure that the "documentation" is expressed in executable English.  ([1] is an attempt to do this.) That way, the business user can go straight to an automatically generated English explanation of the results.

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"?)

--Frank