[ic] Re: [mv] minivend--interchange documentation

[Barry Treahy, Jr.]

Please don't take this wrong, because I was equally guilty of doing this too, but it
seems that about every two months there is a group of new users and the list drowns
in bitching and complaints about how bad the documentation is as well as comments on
how the documentation could be and should be better.

Perhaps as a disclaimer when joining the list, and also placed at the top of all the
existing documents, states up front that "Yes, the MV/IC documentation 'As-Is' does
fall short but that a rewrite is in the works.  Please send comments, complaints,
suggestions, recommendations, rewrites, etc to: docs@minivend.com" or something like
that.

Additionally, stating a prerequisite minimum system configuration and skill set
clearly in the download pages as well as at the beginning of the documents might give
people a better picture that MV and IC are not shrink-wrapped Windozes programs, but
that experience and elbow-grease is recommended...

This might save us all from these sessions that do not ever seem to solve any
problems and simply contributes to the individual frustrations of this list.

Regards,

Barry

draftd wrote:

> ******    message to minivend-users from "draftd" <draftd@hotmail.com>     ******
>
> Hello,
> After reading most of the documentation I could find about interchange, I
> would like to give a few personal remarks. Not that I want to hurt people by
> commenting on their work, but because they really asked for comments on the
> documentation.
>
> What I think is needed most for new users is just a very basic "quick
> interchange introduction".  so for example:
> -a brief explanation of the fact that interchange relies on a server that
> creates html-pages on-the-fly.
> -You can adjust this page-creation and all kinds of database-operations by
> the interchange-tags, but they aren't in the actual html-pages. They're
> needed to build the pages.
> -interchange uses a cgi-script that points to the pages. So their aren't any
> pages in the cgi-bin, pages are in /pages/
> -and most importent: a detailed description of the code of a few pages: eg.
> the index.html, lefside, and a few other. Of course not all of the pages. I
> think it will help new users more to look at a few pages, their code and the
> explanation of what's happening than reading throughout the whole
> all-covering tag reference: what does the ui_template there, this [area] tag
> is used here for...., this is an image from the /thums/ dir etc.
> -.....
>
> I know all these things are fully covered in the reference guide, but if you
> don't know any of the above, it's hard to distinguish between important
> things and "nice add-ons".
> Am I right or just writing a lot of qlksjfghfhgq ?
>
> kind regards,
> Tom
>
> ----- Original Message -----
> From: Greg (Sonny) Cook <sonny@akopia.com>
> To: <minivend-users@minivend.com>
> Sent: Monday, August 07, 2000 9:30 PM
> Subject: [mv] minivend--interchange documentation
>
> > ******    message to minivend-users from "Greg (Sonny) Cook"
> <sonny@akopia.com>     ******
> >
> >
> > Hi all,
> > By way of introduction, I am one of the developers at Akopia.  I have
> > taken on (bravely IMHO) the task of documentation organization for our
> > next release of intervend.  Even though I am personally opposed to
> > documentation, I have a grand vision for a complete set of documents of
> > the project.  Kind of everything from "What's a computer?" to "minichange
> > hacker" level.  There is of course an already extant and rather copious
> > corpus avaliable from Mike.  I've noticed it's still pretty hard to get
> > going though.  At any rate, rather than share my concerns with the present
> > state of the documentation, I'd like to determine what sort of
> > documentation people would like to see.  Also what do you think we could
> > do to the current documentation to improve it.  If you're feeling really
> > ambitious, you could even write all of the documentation I want for me
> > :-}.
> >
> > Currently I am combing through the mailing list archives, trying to rescue
> > usefull information from the past.
> >
> > 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
> >
> -
> 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

--

Barry Treahy, Jr  *  Midwest Microwave  *  Vice President & CIO

E-mail: Treahy@mmaz.com * Phone: 480/314-1320 * FAX: 480/661-7028