Re: [mv] more documentation stuff (fwd)

["birgitt" <birgitt@cais.com>]

******    message to minivend-users from "birgitt" <birgitt@cais.com>     ******


> ******    message to minivend-users from Sonny Cook <sonny@akopia.com>     ******
> 
> 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.
> 

Quite convincing and certainly true to a certain degree. I think most thought
of us thought about documenting the MV tags, not the Perl source code. 

> I love reading documentation, just not writing it. 

Then I would say, don't  write it.. 8-)

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

which might be the logical consequence under the contingcy of getting bullied around...

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

Well, I guess I have nothing more to say due to utter amazement and confusion.
Birgitt 

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

-
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