swarm documentation (was Re: dropping or cleaning a schedule)

[Roger M. Burkhart]

Paul Johnson writes:

> Does anyone have (or is there available, possibly in the mailing list
> archive where I can't find it) a glossary of SWARM objects, which library
> they are housed in, and how they are used, and what for?  I've found the
> swarmdocs, of course, and I've studied a bit about defobj and the others.
> But I feel like a heat bug, poking at random directions in the dark,
> without a MAP or SCHEDULE.  I understand I can screw around with
> Hello.world and the tutorial, and I have, but I still have this unhappy
> feeling of wandering in n-space.
>
> I imagine you have all been through this before?  Just tell me the month
> and I'll check the archive.
> 
> If there is no such thing, well, pooh!  There's no reason every new user
> should have to inductively develop a personal model of the framework. And once
> I do understnad it, you better watch out for an "idiot's guide to swarm" from
> me!  I'll be famous:)

Jim Westervelt published a class tree to the mailing list, available from the
archive at www.santafe.edu/projects/swarm/archive/list-archive.9704/0198.html.

With respect to class trees, it is important to note that there are many
internals to the Swarm libraries that a pure client user of the libraries
doesn't have to know.  This includes many of the classes in Jim's list.
Nevertheless, it's always helpful to understand how things are
structured behind the scenes, and our documentation plans to cover that
as well, though in a different section than the library overviews.

Our plan is that the introductory documentation will continue to be mostly
at the interface level rather than the internal classes.  These interfaces
are deliberately documented only with @protocol (or equivalent @deftype)
declarations in the library header files.

To build better long-term support for the techniques of information hiding
that we use, I'm currently trying to finish up a more generic form of
support for the multiple class implementations that lie behind the many of
the library interfaces.  We've held off documenting (or indexing) the
internal class structures until this support (and associated naming
conventions) has been put into permanent maintainable form.

Ted Belding writes:

> I agree with you completely -- this is the main reason why the docs are
> still inadequate for new users.  The most important thing in any good
> reference manual is the index.  When I was learning Swarm, it involved
> heavy use of grep just to find what file a particular routine or object was
> located in.  I gave up on having any sort of overview on how it all works.
> Documentation should still be the Swarm Team's #1 priority. (If nothing
> else, decent docs would give Glen more time to do actual programming,
> instead of answering questions all the time.)

Documentation is still a top priority.  It's looking hopeful that with new
funding and possible new developers we might get out of survival mode
(Glen as the only full-time developer) and make better progress on top
priorities.

The library reference documentation does need an overall index as Ted
suggests, but all the object types and messages in the example I sent
out are documented, in at least a terse reference form, within the
activity library Interface Reference
(www.santafe.edu/projects/swarm/swarmdocs/src/activity/ref.html).

In addition to the index, I think just as important for the docs is a
tutorial level of coverage on all supported functionality in each library.
I view this as separate from any application, organized according to
topics from the simple and common to the more advanced and specialized,
with example programs that fully illustrate how the types and messages
are actually used to accomplish tasks.

This manual is not a reference manual, but is usually the more useful
both for new and experienced users, to the degree that it gives a balance
of both generic explanations and specific examples.  A good example is
the Kernighan and Ritchie C book, in which the "Reference Manual" is
a highly condensed appendix, but all the explanation is in the topical
organization of the main book.  (It was good enough to serve me as my
only C book, with the ANSI standard serving as my reference manual
later on.)  An object library does need more extensive reference material
(compare, for example, the book on the C++ Standard Template Library), but
even there the reference manual is backup to usage examples and explanation.
In our documentation outline, the "Usage Guide" section of each library
is our placeholder for the tutorial coverage, but the current material
there is just gathered from what was lying around rather than being what
is really needed.

Everybody please note -- Swarm is a community-based development effort in
which we hope that many different groups can develop and share both code
and documentation, or anything else that can help others who might have
the same needs as your own.  We're in the process of putting together a
more versatile organization to help fund and coordinate some of the core
needs that everybody has, but nobody needs to wait for this to make any
volunteer contributions.  Paul's offer to put together an "idiot's guide
to swarm" is exactly the kind of return to the larger community that we
hope everybody feels free to provide.  And, yes, this is an excellent way
to make yourself famous, as has occurred for people making such effort on
many other public software packages.  Becoming well-known in this way is
one of the best ways to influence and participate in the direction of a
software package, and that means there can be real opportunities (and
justification to your organization) for contributing such work.  If the
documentation is incomplete, please anybody feel free to help fill in
missing pieces, and you're sure to get lots of help to explain the stuff
that needs to be made clear.

Roger Burkhart

                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.
                  ==================================