Swarm User Guide (was Re: built in rv objects -- "bug" in documenation)

[Alex Lancaster]

>>>>> "BS" == Benedikt Stefansson <address@hidden> writes:

[...]


BS> How about jump starting this process by setting up a Faq-o-matic
BS> on the SFI site where one could contribute things such as the info
BS> that went back and forth today on swarm-support about random
BS> number generation?  Anyone with an urge to contribute nice hacks,
BS> stupid Swarm tricks or answers to questions on swarm-support,
BS> could simply edit his answer and contribute it to the FAQ (I think
BS> that questions should still be directed first to the list). A jump
BS> start to the jump start might be to cull the most frequently asked
BS> questions from the swarm-support list...

The model that I'd prefer to run with, for creating User Guide content
is to `commission' (voluntarily, of course) people for the various
parts of content that they'd like to see in the Guide.  We could lay
out a number of areas that need content, folks could suggest them as
well, then we'd set some contribution deadlines and people get
writing!  Paul, Benedikt and I can function as both contributors (I'm
hoping to write some material on the activity library, for example)
and editors (I will also double on the production side, putting things
in SGML, as I can understand that most people won't want to contribute
in SGML form directly).

I think this would work better than having people post bits and pieces
to a FAQ, that some unspecified people merge into the User Guide, for
several reasons:

1.  There's a larger incentive to produce quality material - the
    contributor's name will be associated with the section, the
    contributor will have more of a sense of `responsibility' for the
    information in the section.  

2.  One of the problems with a FAQ-type approach, is that it puts the
    onus of information maintainers on the folks that maintain the
    server-end of the FAQ, rather than the contributors.  The bottom
    line is: it's easy to whip up a couple of paragraphs on some Swarm
    factoid or other and rely on others to re-write it, than it is to
    take responsibility for deep understanding of some particular
    aspect of some software and spend some time translating that
    information to non-specialists.  I don't think we have a problem
    with the *quantity* of information on Swarm, it's *quality* that
    we need to be concerned about, and generating quality `User Guide'
    content is a non-trivial matter (which is why technical writers
    exist).

3.  Having it partitioned up (to some extent) like book chapters,
    should have the effect of reducing overlap in content coverage.

4.  The cost of taking a lot of `bitty' and sometimes `soft' (in the
    sense of not being general enough) information in FAQ form and
    massaging it into reasonable prose, suitable for a `User Guide' is
    larger than generating that prose in the first place.  This is not
    to say that FAQ information is not valuable, in it's own context,
    just that it's not the appropriate place to start when generating
    information intended for longevity.

BS> I know that Paul already has a Faq-o-matic for Swarm installation
BS> problems, but I think it makes more sense to run this out of SFI,
BS> for example so that Paul doesn't have to be responsible for
BS> backups, and also because one of the resident hivemeisters could
BS> then merge this 'emergent information' into the user guide
BS> (fanfare) with all 'em fancy XML tools you young people use today.

I'm pretty reticent to setup a new FAQ for Swarm, for the reasons I
outlined above, and I think that Paul's FAQ is motoring along just
fine.  We at the SFI Hive have really already got our work cut out for
us, maintaining amongst other things: the Swarm source tree, numerous
Swarm applications, SGML documentation, Documentation tools, the
Windows InstallShield, SwarmFest registration forms etc...

As far as the idea of merging the `emergent information' with our
`fancy XML (sic) tools', goes, that's fine with me - I'm happy to do
that, but I really think the the bar for contributions needs be higher
than that for the FAQ.

Regards, 

 --- Alex

-- 
  Alex Lancaster           |  e-mail: address@hidden
  Swarm Program            |     web: http://www.santafe.edu/~alex
  Santa Fe Institute       |     tel: +1-(505) 984-8800 (ext 242)
-------------------------------------------------------------------

                  ==================================
   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.