Re: [mv] use of demos as starting point

[Chris Rapier <rapier@psc.edu>]

******    message to minivend-users from Chris Rapier <rapier@psc.edu>     ******


Steve Fairhead wrote:

> >> There are so many mailings from beginners on this list about the
> difficult to install minivend an the poor documentation, so the people are
> using 'simple' as a reference (including me).
> 
> But this seems to be the wrong way to go. <<
> 
> Really? The documentation etc states quite clearly that the demos are the
> place to start, and that many folks use production systems based on tweaked
> demos. If so (and it's certainly true for me: the more complex demo is
> tantalisingly close to what I need) then we're in trouble :).

Well, the thing is that its really not an either/or option here. The
demos are very useful and I based on of my sites on one of them. They
provide an excellent way of showing what can be done and give you the
necessary tricks to do it. 

HOWEVER! That being said, the problem with the demos is that they don't
actually teach you the underlying rational behind what they are doing.
Its more than possible to develop a site without actually knowing *why*
you are using a specific tag in a specific place. Without the knowledge
of why you are doing something you'll never really understand what you
are doing. Without understanding you'll never be able to really develop
the full potential.

E.g. For my day job I do a lot of network engineering. Some of this
involves giving talks and presentations on TCP performance tuning. This
necessarily deals with issues of flow control and ACK behaviour  - both
of which are *fundamental* to TCP (in fact, you can argue that ACK
behaviour is *all* that TCP is about). Most of the questions I receive
regard the most basic principles of ACKs, things these people, as
network admins and engineers, should know. How can these people, in
charge of major universities and commercial networks, not know this
stuff? Because they learned how to do what they do by following the
examples. They learned which switches to flip and what config files to
modify but they don't really understand why they are doing it. Because
of this I've been working on a 3 hour tutorial to cover IP basics.

What I'm getting at is that examples are an important part of
documentation but only a part. You need to have fully and well developed
documentation so that people can really understand what and why they are
doing something. I know how difficult and boring documentation can be so
I'd like to propose something...

We have a lot of people on this mailing list who know quite about
minivend and the fundamental concepts behind it. However, no one person
has the time or inclination to do the whole thing. But what if we split
the task up? What if we had people volunteer to document smaller
(perhaps much smaller) portions of minivend? For example, someone could
take "Installing Minivend", another could take "Minivend and PGP",
someone else could take "Minivend and Cybercash", or even "Minivend and
Database Design", and so forth. Its goal won't be to replace the
existing documentation but to expand on it with insights, examples, and
the "whys" behind it.

If there is interest I'll do my part to help organize it and write it.
Anyone else?
-
To unsubscribe from the list, DO NOT REPLY to this message.  Instead, send
email with 'UNSUBSCRIBE minivend-users' in the body to Majordomo@minivend.com.
Archive of past messages: http://www.minivend.com/minivend/minivend-list