Re: Minivend Documentation

[Birgitt Funk <birgitt@minivend.com>]

******    message to minivend-users from Birgitt Funk <birgitt@minivend.com>     ******



On Fri, 19 Feb 1999, Barry Treahy wrote:

> ******    message to minivend-users from Barry Treahy <treahy@mmaz.com>     ******
> 
> mikeh@minivend.com wrote:
> 
> > ******    message to minivend-users from mikeh@minivend.com     ******
> >
> > First, we need to find out how people are using the current documentation,
> > what parts they use and which parts they don't, in what format, and why.
> > Once that input is in, we can start.
> 
> Hi Mike, as I've been asking for the past couple days, I use the ALL.HTML version
> extensively...  Why? Because once I have it in my browser, I can easily search for
> specific key words, examples, etc.  That is why I've been asking what happened to
> it and it has gone unanswered.
> 
> Also, the all version is best for printing where as the frame/no-frame version
> requires too much work.

Agree strongly. We need the "all in one" file. I need to work with a
print-out. Online reading time is expensive in Germany. 

I even pull all answers in the list which seem valuable to me for future
use, out of a printed version of the condensed list archives.

What I use of the documentation and what not ?
     All of it. But I restarted working with MV only two weeks ago.
     Last closer looks at the docs where in 1997. 

Wishlist:

1.)  A COMPLETE list of all tags: 
     a. with a more wordy type of explanation where they come into use.
        For me some of the explanations are too much in telegram style.
     b. with more examples supporting the explanations given.
     c. with more hints towards what kind of applications they could be
        used for, avoiding technical lingo as much as possible. This will
        be read by many non English native speakers, who learned
        programming in their own language. So syntax and code is not the
        problem but some technical verbiage might.

2.)  A clearly stated list of all packages and modules needed, short
     explanation on how to install them and in what order.
     Follow the path of someone, who has nothing but a server and 
     Linux CD distribution at hand and is setting up one package and
     application after the other. Sally's last post about what the
     ISP she promoted is offering, gives a nice overview about what
     really is needed to set up a fully functional server with MiniVend.
     Hints to pitfalls to be aware of.

3.)  An overview of each file and directory MiniVend contains and
     produces, with a short explanation what each file is for in the
     introduction. In English. 

4.)  A map between tag functions and where to look in the source
     to find the relevant code which make the tags do what they do.
     Would be of great help for someone learning Perl.

5.)  More thorough explanations about how pgp, glimpse, secure server,
     mysql and possibly cybercash are working together. More explicit
     pointers to helpful beginner documentation.

6.)  In the various subject areas of the documentation, just get more
     explicit, more examples. 

OK, to be frank, I like cookbooks. And I think Mike Heins doesn't. 8-)

I am not sure, I would give my best recipies away in a nice cookbook I
had written for absolutely nothing, and now, where the documentation
project is called into life, I am not sure, if what I like to see, is
acceptable to ask for.

I would be more than happy to help with a German translation, provided I
am guided closely through the process by technical experts.

I admit, I sit on literally meters of English and German O'Reilly
titles, I was going to study after a long twisted journey to get that
point anyhow. So I am equipped in that regard. 

Actually I anticipate the documentation project to become a very
rewarding experience for me if allowed to participate in it.  

Birgitt Funk




-
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