SCOUG-Programming Mailing List Archives

<< Previous Message << >> Next Message >>

Date:	Sat, 9 Aug 2003 15:37:29 PDT7
From:	"Lynn H. Maxson" <lmaxson@pacbell.net >
Reply-To:	scoug-programming@scoug.com
To:	< "scoug-programming@scoug.com" > scoug-programming@scoug.com >
Subject:	SCOUG-Programming: English as programming language (was: Warpstock 2003 Presentation)

Content Type: text/plain

"...My push for English is fundamentally a documentation issue.
Document the problem, document the potential solutions, test
until you're happy without regard to the programming
language used (or perhaps using something other than a
digital machine). ..."

Peter,

I should have guessed that without Steven to prod a bit that
you might zero in on someone else. You apparently missed an
earlier message on Bob Blair's interest in the "front end"
development as it addresses his interest in literate
programming. You remember literate programming, a method
proposed by Donald Knuth to incorporate two equal but
separate languages, one formal (code), one informal (text), in
a document. It allows the same content to appear in different
contexts, e.g. in a language reference manual and a user's
guide.

For the curious about a working literate programming system I
suggested a google search on "noweb literate programming".
You would probably get a similar response but different
source for "web literate programming". In either case you will
see serious efforts at providing the level of documentation
that you seek.

Notice, however, that while you can have informal text
associated with code and appear in a view "with" the code it
is not "in" the code: it is not the same as "commented" code in
which code and text are physically bound.

The data repository/directory in which all source, code and
text, is stored does so at the statement/sentence level. That
means every statement, every sentence has a unique,
system-assigned name. Every assembly of code only, text
only, or of code and text has a name (a list name) which
references a list of names of source elements (statements and
sentences) or source assemblies.

It's a pure Bill of Material (BOM) manufacturing system. Like
any such system it allows you to "explode" an assembly down
through its hierarchy of lower level assemblies and raw
materials ultimately down to a list of all the raw materials
(statements and sentences) used. It also allows you for any
raw material or assembly to create a "where used" used
listing. This latter allows you to make a change to source
code, produce a listing of all affected assemblies, and alter
the source text in those assemblies to correspond to the
change.

In short literate programming does not automagically update
documentation. It does, however, allow you to search on
existing associations (as well as providing for new ones) to
each the task of synchronizing changes to code and code,
text and text, and code and text.

As you know documentation like the poor, sick, elderly,
enfeeble, and non-voting populace is the first to find itself cut
off from funding, the first viewed as too expensive, and the
first to be discarded under the pressures of a deadline. It's
also the first statement of need when the time comes to
overhaul an application: "we must first document it."

So far from giving it short shift in my proposed system I give
text (or in your words documentation) the same level of
productivity that I give code creation and maintenance. We
haven't focused much on it, except for Bob Blair's interest in
pursuing the "front end", because it is not a formal
programming or specification language per se.

"...So tell me, Lynn, what part of Open Source are you going
to open? Might you consider a subtle topic change, say to
"Opening Open Source To Include Documentation"?"

The "opening" here refers to opening up its supply of
contributors by significantly reducing what exist as technical
and psychological barriers. How do we get more people to
program? What can we do to make them more willing to
participate? How can we increase their comfort zone?

I simply picked what I considered both a succinct and catchy
title that would attract more attention as well as interest,
curiosity actually, in hearing more. I didn't exactly fail with
you, but it does point out what place ambiguity in english has
in providing different interpretations in different people of the
same text.

=====================================================

To unsubscribe from this list, send an email message
to "steward@scoug.com". In the body of the message,
put the command "unsubscribe scoug-programming".

For problems, contact the list owner at
"rollin@scoug.com".

=====================================================

Return to [ 09 | August | 2003 ]

SCOUG, Warp Expo West, and Warpfest are trademarks of the Southern California OS/2 User Group. OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks remain the property of their respective owners.