Re: Documentation Project

[Birgitt Funk <birgitt@minivend.com>]

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



On Sat, 20 Feb 1999, David Ekholm wrote:
> If I may add a couple comments off this topic.
> 
> Better Documentation - I wholeheartedly applaud Mike's effort to improve the
> documentation.  Although it's pretty good, considering Mike isn't at all
> compensated for doing it, it has often driven me crazy because of it's lack
> of examples and occasional gaps (like the incomplete tag list).  I would be
> more than willing to pay for more thorough and easy to use documentation.
> 

Me too. I would like to throw in something in direction to Thompson Jordan
and perhaps Mike Heins.

In his first reaction to the documentation evaluation Mike said:
  > thinking about getting a professional to do a real manual and then
  > sell a CD-ROM with a manual and a CGI user interface to MiniVend.
His second reaction was the announcement of the documentation project.

When thinking about the different knowledge base of MV users and what
they might wish for in the documentation, I think it should be clear,
if one 
a. makes a free documentation which accompanies the free software
b. produces a manual/handbook which accompanies a MV-CD-ROM (like you
   find smaller handbooks in Linux distributions for example) or 
c. works on something like a (hand/cook/reference)book which contains a MV
   CD-ROM.

If it is a free online downloadable documentation like it is right now,
one can not possibly ask for much more than cleaning up the tag reference,
adding more examples and being perhaps a bit more explicit, wordy etc.
(I like BTW Dan Busarow's idea of gathering user provided code examples
on the web-site). 

If it is a manual which accompanies the CD (i.e. you buy a software box
with a manual inside), one would add more how-to style sections for 
the various installations and configurations procedures, more explantions
a MV hosting service provider might be interested in. (You get what you
pay for).

If it is more like a book, one has to determine which readership one
wants to address. There are so many different flavours. An official
guide type of book, a reference book, a how-to cookbook, an easy-going
introductory type of books etc.

I am just mentioning it, because I realized when starting to translate
that things I would want to add belong in different styles of documents.
I would not want to bore with inappropriate suggestions just because
it might not be clear on what we will be working on. 

I am not quite sure if it is still alright to post this here or if
I should just have sent this to Thompson-Jordan or just not at all. 8-)

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