[Date Prev] [Date Next] [Thread Prev] [Thread Next] Date Index Thread Index Search archive:
Date:Mon Apr 13 22:22:55 2000 
Subject:Documentation and popcore (Was: Possible Poplog Projects) 
From:Aaron Sloman See text for reply address 
Volume-ID:1000413.03 

This message describes the Poplog Help File Finder project at sussex
in the 80s and mentions the file TEACH POPCORE at the end.

"Jonathan L Cunningham" <jlc@sofluc.co.uk> wrote in response to one
of the points in Steve Leach's original message:

[SL]
> >1. Documentation project
> >
> >     Although Poplog's documentation is actually very fine,
> >     new users have difficulty finding their way around.
>
[JLC]
> This sounds a leetle like an oxymoron, n'est pas? If it is
> not an oxymoron, and the new users are not morons, then it could
> just be that poplog is too Titanic. (Deliberate connotations.)

Actually I have had the same problem with the documentation in
Poplog on the X system. In one sense it is very fine (there is a
huge amount of it, and it is very systematic and for a user
knowledgeable about X it is extremely useful). But in another sense
it is not at all fine: users wanting to learn how to do things in
Pop-11 without having to first learn the basics of X by reading
other things (like me) can find it very difficult.

There are some exceptions: namely a few very useful introductory
files, e.g. teach motif, teach athena, teach Xpw, but they take
you only a very little way in.

This is a general problem with any very large, multi-functional
system about which a large amount of information needs to be
provided for different sorts of users, or for the same user with
different sorts of requirements.

There is NO general solution, I believe. As Jonathan says:
> There is no single solution. No solution will suit every new user.
> Every (category of) user will need a different solution. (Snark
> hunters will see the significance of this paragraph.)

We once had a research council grant to work on this in the mid 80s. It
was called the Help-file-finder (HFF) project, and for a time employed
Tom Khabaza working with me and then Andrew Law, and for some of the
time David Allport who was working on his MSc at Sussex did
a related project including developing a parser for questions
from novices.

The HFF project started from the observation that experienced poplog
users found the documentation available then very useful: they could
often find what they needed, whereas newcomers just saw a large
unstructured mass of information. However we also noticed that very
often a newcomer could ask an experienced user a question and even
if the latter did not know the answer he could provide a pointer
to some part of the documentation which led the novice to the answer.

We considered and quickly abandoned keyword based searching tools.
There was a lot of evidence that finding a suitable set of keywords was
very difficult or impossible, and poplog was likely to be too complex.

We considered and very soon abandoned the idea of developing a
traditional expert system to perform the function of these
experienced users. It was clear that that would be way beyond the
state of the art.

Moreover David Allport's work showed that novices would pose questions
in a form that often required highly creative parsing by the expert, for
instance because the questioner would mix up Pop-11 and English without
any markers:

    Is there something related to foreach as allpresent
    is related to present?
    (No quote marks)

or worse, given that many words of pop-11 and of English overlap,
things like:

    Can I use if in an until loop?

Anyhow, we decided that the only inference engine powerful enough
for the purpose was going to be the user's own brain.

So we decided to create a carefully selected collection of entry points
into the documentation, such that if novices learnt to use those entry
points they would get into shallow searches that fanned out quickly to
the required information file.

We viewed the documentation as hypertext (for which Ved gave support
with the "ESC h" command, and still does) forming a graph made of a
collection of superimposed trees. So the task was to identify the
trees and provide good help files which could act as their top
level (or, if you prefer, root) nodes.

Those root nodes did not merely provide content about the
editor, the language, the external interface, etc.

Rather they also *described* the types of contents available and
provided pointers to files which had the content at a suitable first
level, many of which would then include pointers to other files
providing additional content (and with many cross and back
pointers).

(Sound familiar?)

Some of the trees (and their root nodes) were for (almost) novices

    HELP VED
    HELP DOCUMENTATION
    HELP HELPFILES
    HELP POP11
    HELP SYNTAX
    HELP LOOPS
    HELP NUMBERS
    HELP PROGRAMMING

Some were for more experienced users

    HELP CONTROL
    HELP DATAPROCS (now out of date?)
    HELP CLISP
    HELP PROLOG
    HELP PML
    HELP LIBRARIES
    HELP CLASSES
    HELP PROPERTIES
    HELP EXTERNAL
    HELP NEWMAPPING
    HELP MATCHES

etc.

and for people getting updates:
    HELP NEWS
    HELP LISPNEWS
    HELP XNEWS
etc.

As part of the process a lot of files were re-written to conform to
the proposed documentation architecture.

After the project ended many others contributed further documentation,
much of it excellent, and many of the old files were further revised,
etc.

But I think it is fair to say the task of producing adequate, complete,
well-indexed documentation grew enormously as Poplog grew (e.g. the
addition of X produced a huge collection of additional material to be
documented, and although I believe the documentation is nearly complete
at a certain level, the support for multiple types of users was never
achieved (a) because the resources were never available and (b) because
doing this would also have required producing a lot more libraries and
demonstration programs to hide the gory details of X.

(My RCLIB package has such a collection of programs, but the
documentation is far from adequate: e.g. there are not properly
indexed REf files: it was all done in my "spare" time.....)

Likewise the addition of Objectclass added a whole new slew of
documentation: adequate for certain sorts of users, but not necessarily
for all types.

> I suspect that the desire to impress with how wondrous it is,
> has frequently tempted documenters to provide too much, not too
> little information.

This may have been a problem (especially in some of the more verbose
"teach" files, including many written by me) but I think that was a
shallow aspect of the problem.

The deeper problem was a logical consequence of

(a) the huge amount of information that required to be documented, about
the various languages, the virtual machine, the external interface, the
editor, the X system, and various non-trivial packages (e.g.
objectclass, regexp, flavours, the library mechanisms, lib debugger,
the tracer, lib lr_parser (a parser generator) etc.)

(b) the different kinds of uses to which Poplog could be put, requiring
different kinds of examples, different levels of explanation, etc.

(c) and the different kinds of users e.g. novices to programming, expert
programmers who are novices to poplog, expert programmers who know
poplog well, experts who know about one of the languages but not the
others, etc. etc.

To say nothing of Emacs users who refused to switch to Ved, for whom
the format of the documentation proved a serious obstacle after the
"graphic" characters were introduced.


Jonathan also wrote:

> I'm minded of previous suggestions of
> isolating a "tiny pop" subset - and documenting that. Indeed, I
> believe somewhere I have such (on two sides of A4, written by
> Mike Sharples?).

This tiny subset was used for this Book and presented in its appendix:

    Sharples et. al.
    Computers and Thought
    MIT Press 1987

In my experience as a teacher this remains a useful introduction
to computational cognitive science for computational novices.
Many of the "standard" AI textbooks move too quickly for some
of these students.

But this book is a bit dated, and unfortunately, in my opinion,
uses only vars, not lvars.

Mike's file can be browsed here:
    http://www.cs.bham.ac.uk/research/poplog/help/tpop

A few years ago I produced an extended version of
that file called TEACH POPCORE. It can be found here:

    http://www.cs.bham.ac.uk/research/poplog/teach/popcore

I have a latex version which prints as 12 pages, or 6 sheets
printed two-up.

I think it contains most of what the weaker to middling students
here in Birmingham need to get through the first year of AI programming
using Pop-11, apart from the extensions such as Objectclass and
Poprulebase, for which there are separate introductions.

Apologies for length.

Aaron