Roedy, is there anything that *isn't* on your site?
I've been adding to the glossary almost daily since 1995. I too am
often surprised what I find in there that I forgot I wrote.
I get emails from people who land somewhere on the NON Java part and
they emerge several days later, intrigued chasing ideas.
I see various things in newsgroups I don't recognise. Struts for
example has not yet made it to the glossary. I have no clue what it
is. It has a name designed to make it hard to Google.
I don't like to write about something until I am fairly sure I know
what I am talking about. I get vicious blasts for even the most minor
errors. Yet all new entries are about new things I am just learning
too.
People won't supply text for the glossary, but they are fairly good
about bawling me out for saying something wrong or that they disagree
with. So sometimes I just put out my best understanding and wait for
the feedback blasts to correct it.
My goal is just to get people started, to give them an overview of
what something is for, and also the few gotchas they are likely to
trip over when they start implementing. There is plenty of detailed
docs. I try to provide the bird's eye view and just enough to
demystify to encourage experimentation.
If people would document their packages in a top down way the way
Freemarker was done, much of what I do would be unnecessary. The irony
is the best documentation of a Java app in English was done by a
Hungarian. It has a few strange bits of Hunglish syntax, but the
methodical way it explains what each tool is for before getting into
the details of how to use the tool makes it a joy to read. Most people
writing are far too afraid of simple examples. I think they imagine
examples detract from the dignity and magnificent generality of their
work.
