I have recently had the need for a parser.  The grammar I have to
parse is reasonably simple but I have studied and written enough compilers
in these past fifteen years to know better than hand-coding a parser myself
(actually, the lexer is usually what turns out to be the trickiest part). 
I used to use lex, yacc, bison, etc…  in the past so it was only
natural to take a look at ANTLR and JavaCC.

Since I am fairly familiar with this family of tools, what I am looking for
is pretty simple:  a tutorial that will quickly fill me in on the syntax
used to describe the lexer and the parser and how to invoke the tool.

ANTLR provided me just that.  The home
page leads you to a Getting Started guide that tells me
exactly what I want to
know.  After ten minutes of research and reading, I feel qualified to
start writing my first ANTLR grammar.

The experience with JavaCC was…  quite different.

First of all, JavaCC’s home page
doesn’t make the documentation link very obvious. Scroll to the bottom to find a
few links, but even this doesn’t turn out very useful pointers:  FAQ,
repository of grammars, installation and getting started (which actually only
tells you how to install the software but not how to use it) and finally the
complete documentation.

I am not looking for the complete documentation but I am running out of
options, so that’s what I end up clicking.  The page itself is still not
the "complete documentation" but yet another collection of links that I have to
wade through in order to find what I am looking for.  Needless to say my
patience is running thin at this point and I am about to give up, especially
when I see that the only tutorials on this page are about how the "lookahead
processing" is performed and how the token manager works.

At this point, I just give up and I know I’ll be using ANTLR.

Here is a quick advice to everyone who wants to make their software
appealing:  I know how tempting it is to expose the technical brilliance of
the internals of your software, but just don’t give in to it.  Think
carefully about your users, ask yourself why they would want to use your
software and make sure that you design your documentation and your Web site with
that in mind.