Re: documentation discussion (was: Re: [mv] IF tag: [ifsession login] doesn't work?)

[Mark Stosberg <mark@summersault.com>]

******    message to minivend-users from Mark Stosberg <mark@summersault.com>     ******


One more thing to add to the thread on a minivend documentation database:

Databases work well when they have structured data. In the context of
Minivend documentation, I think a database would work best for
documenting the tags, because tag could probably be described with the
same structure of documentation. 

However, the parts of the documentation that are currently flowing
paragraphs of text may best be left that way. 

I think what's most important is having a specific structure for
documentating the tags. Mike has already done this in the current
implementation of the docs, although the content is incomplete and
lacking examples built into that system. But it's a good start! 

It may be possible to build a good web interface to suggest updates to
the the tag docs, while still maintaining "pod" as the underlying format
as it is now. "pod" is nice because it's easy to write, and easy to
generate both man pages and HTML from it, and there are a lot of tools
to deal with it already. There's also something to be said for simplicity!

To be more concrete, here's a spec for the usage model of potential
system, as I might design it. 

* This spec applies just to tag documentation, seen here for example:
http://www.minivend.com/minivend/tags/03.11.currency.html#currency

* A user visits the documentation on the web. She notices that the
documentation could be approved. She clicks on a link on the page
labeled something like "Propose an update to this tag documentation". 

* A web form pops up with the content of the documention populating the 
fields of form. 

* She edits the documentation in the form fields as she sees fit,
and clicks submit. There will have to be some notes around the form
describing how to preserve and create formatting. 

* A message is sent to minivend-docs mailing list with the results. 
There it is discussed by interested folks. 

* Mike makes any final notes and corrections and integrates into
the official docs if he approves it. 

The details of this system could be implemented with or without a
database behind it, and depending on what the details are, it may make
more sense one way or the other. :) 

Another suggestion: Perhaps for those interested in discussing this
further, it would make more sense to do it on the minivend-docs list. :)

    -mark

  <<-------------------------------------------------------------->>
personal website                <    Summersault Website Design
   http://mark.stosberg.com/     >       http://www.summersault.com/
-
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