re: declaration section of ABNF -- beginners

On the subject of free declaration order vs. beginners...

I am a very new beginner to VoiceXML. In my opinion, there is no real advantage to beginners to having order free declarations. To the new and unacquainted beginner everything is new; so, it just doesn't matter one way or the other. Order is good. No order is good. It just doesn't matter. What does matter is good documentation accompanied with a great index.

Speaking as a self taught programmer of 16 computer languages, here's my opinion of what would help:
  1.. Start with a web based documentation written to an audience of beginners that progresses from beginners to advanced users. 
    a.. Add a Boolean search engine (with a NEAR function) to search the web based documentation.
    b.. Speed documentation development by allowing web users to suggest corrections and/or improvements to documentation.
  2.. We need a great index. A great index is the most important part of any teaching document. Most people think of an index as a concordance, but a truly great index is more. A great index allows users from different lines of thinking to find the same information from more than one point of view. For example an index with just "volume p.138" isn't as useful as an index with "loudness p.138", "sound level p.138", and  "volume p.138". The easiest way to get this great index is to put it on the web and allow your web audience to contribute by suggesting their index words and were it was they found the related information.
  3.. Plenty of short and to the point examples. Examples alone are good, but not great. This is how you can move from good to great.
    a.. Include the purpose of the example programs in the index (again in numerous places like volume, sound level, loudness, etc.), but set the examples apart in the index by color and/or font.
    b.. Allow the web audience to submit and comment on the examples, and give a ranking approval to each example and comments in the example. 
    c.. Create a web based Boolean search engine to sort through the example programs (and provide a comparison table of occurrence and user approval).
    d.. A concordance of commands that gives reference to every line number of every example that uses the command. Show the line as a link that when clicked take the user to the full program with the opening position being the line.
    e.. A command list with a "see also" to easily find related commands.

On the subject of Tag format vs. beginners...

Personally, I wouldn't know a Tag if it walked-up and hit me, but here's a lesson from C++ in relation to beginners. Right now the C++ Standards Committee is trying to make C++ easier for beginners to learn, and one of the problems that makes learning C++ hard; is that C++ has some inconsistencies. What is an OK format in C++ core language isn't OK in some cases inside a C++ library or visa versa, and it makes learning C++ harder! 
 
From a beginners point of view, I don't want to see Tag format as one way, and Mode format another way. It's to confusing when format is different. If you want VoiceXML to be easier to learn, then I would suggest every effort be made to have an overall consistent format and/or approach for the entire language. 


Thanks for your consideration

I once worked at a company where new ideals were their stock and trade. I was told the main rule for brain storming was, "There is never a bad ideal. No matter how silly, how unworkable, or how out-of-context and ideal is; there is no predicting the genius it will give birth to in another mind." I want to express a special thanks to Jim for his courage to express his opinion and give seed to my thoughts. It's my hope this email will give seed to someone else's mind.


Regards,
Alan Bundrant


----- Original Message -----
From: "jim jackson" <jf_jackson@hotmail.com>
To: <www-voice@w3.org>
Sent: Wednesday, July 10, 2002 5:03 AM
Subject: declaration section of ABNF


>
> Hi,
>
> A couple or remarks:
>
> 1. Order of declarations. It was fixed in the previous Draft and now
>    (in the candidate recommendation) declarations may appear in any
>    order.  Actually I find this freedom harmfull for readability: if
>    you're used to find always base, language, mode, root, tagFormat,
>    lexicon, and meta, then getting the declarations of a new grammar
>    is just easier; and writing a new grammar is just as simple.  From
>    a software engineering point of view, it's like parameters for a
>    function.
>
>    To me, making the order free helps only beginners as grammar
>    writers; it's useless if you're not a beginner and it's confusing
>    if you're not a writer but a reader.
>
> 2. Tag format.  The candidate recommendation states that, for a given
>    grammar, lexicon and meta declarations may appear any number of
>    times, that language must appear exactly once, but it doesn't state
>    that tag-format can appear at most once (which is stated for base
>    and root) and I don't think that several tag-format declarations
>    make any sense.
>    [this can be solved syntactically: by reintroducing the fix order
>    of declarations and making tag-format optional at its place, as it
>    was in previous version of the document!-)]
>
>    Furthermore, the tag-format should be like the mode: you cannot
>    have a grammar in voice mode that uses a rule from a grammar in
>    dtmf mode.  Similarly, I don't think you can mix two grammars that
>    have different tag formats. Well, you could but it would require
>    that further specification of tags is provided in the document.
>    Currently, the tag language is defined externally: not only the
>    syntax of this language but also its semantics, the kind of
>    computed information (character strings, objects, raw data,
>    attributes...), the data format, the way information is processed
>    along the Logical Parse Structure (Appendix H), i.e. along the
>    parse-tree (top-down, bottom-up, depth-first traversal,...), and
>    everything I'm forgetting...
>
>    I'd suggest mixing tag formats is forbidden like mixing modes.
>
> Regard,
> Jim
>
>
> _________________________________________________________________
> Send and receive Hotmail on your mobile device: http://mobile.msn.com
>
>