[mv] more documentation stuff (fwd)

[Sonny Cook <sonny@akopia.com>]

******    message to minivend-users from Sonny Cook <sonny@akopia.com>     ******



---------- Forwarded message ----------
Date: Tue, 8 Aug 2000 20:16:07 -0500 (CDT)
From: Sonny Cook <sonny@www.akopia.com>
To: minivend-users@minivend.com
Subject: more documentation stuff

Hi,
It's nice to see an enthusiastic response to my project.  I'd like to
address some of the issues brought up so far.  I am doing so from memory,
so if I leave something out, I may have just forgotten it.  Let me start
be answereing why I am against documentation.  I am a programmer and so my
code (which is also bug free) documents itself.  I shouldn't have to
exp[lain in english what stuff does when I jsut finished explaining it in
perl to the computer.

I love reading documentation, just not writing it.  In fact if I can hire
a tech writer to bully around in time, I won't have to write it.  As the
chances of that seem to be wisping into smoke with every passing day--it
looks as if I might end writing some of it at least.

It seems that there was a big call for improved (completed) handychange
tag reference.  With complete explanations, parameters, anotations,
dependencies, caveats, and even previously undocumented features.  This is
a rather herculean task--which will not appear in the next release.  We
will work on this, however, do not despare.  One point that a couple of
folks mentioned that I failed to appreciate was the need for CLEAR
language usage.  In my Americanocentric bubble it completely failed to
occur to me that others cannot speak englich as poorly as I can, and so my
tendancy to create complex (and sometimes esoteric and subtle) grammatical
towers--a virtual babel so to speak--would be less than appreciated by
others, and therefore I shall forebear.  Good point.

Examples--lots and with explanations.

More accessible organization of the present documentation which can be
annotated.

Your comments have helped me clear up my vision quite a bit.  Here is a
summary of what I hope you can expext with the next release.

Some basic stuff:
	how to install intervend
	how to configure the demo store
	run though of the demo store
Less basic stuff:
	overview of the minichange system
	annotated templates (different from the demo store)
	really good explanations of the various configuration files
	how-tos for various and sundry things people may wish to do
Not basic stuff:
	indexed searchable tag reference which will be annotatable
	improving the tag reference
	Walkthrough for creating a new intervend site implementation from
scratch.
	improved organization and accuracy of current documentation

Okay then I'm sure that does not cover everything, but it's probably a
good start.  I have a good rant on documentation which I will keep to
myself for now.  Suffice it to say I think that good documentation is very
important for mintervange (since Mike has already done all of the hard
work.)

Thanks,
Sonny Cook

-
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