[antlr-interest] ANTLR documentation restructuring

[Daniel Gackle]

> By the way, Ter (and I'm gonna help) is about to embark upon a
restructuring
> of the docs and website.  It would help a lot if you could explain how the
> documentation should be, in your opinion.
>
> Monty

If I may offer a suggestion, I've spent a lot of time poring over the
documentation, and it would be worlds easier if care were taken to define
each notion before using it.  The way it is structured now is sort of like
this: X is explained using Y and Z, Y is explained using X and A and B and
C, Z is explained in terms of A and Y and D, C and D are not explained
anywhere and, well, you get the picture.  It's the sort of documentation
that makes perfect sense if you already know what everything means, but is
hard to break into if you don't, which kind of defeats the purpose of
documentation.  I don't doubt that this is partly because of the high level
of expertise of the authors.  It is often difficult to temporarily forget
what you know in order to walk someone step by step into that knowledge.

Of course, you can't explain everything back to the beginning of the world,
but it is certainly possible to say, "an introduction to X is out of the
scope of this document, here are some good sources to learn about X".

I have really come to appreciate ANTLR as an excellent tool, and have also
gotten good information from the docs, so I hope my remarks don't sound
cranky.  I do believe that ANTLR would profit immensely from an orderly,
clear exposition.  In my dreams I imagine something like an O'Reilly book...
a solid O'Reilly book on ANTLR would really make the power of this tool
accessible to the wide audience it deserves.

- Daniel Gackle


 

Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/