You call the static method XMLEventFactory.newInstance() when you want to create new instances of XMLEventFactory.
Sun's online tutorial bombastic headache-inductive style (taken from: Sun's tutorial):
New instances of the abstract class XMLEventFactory are created by calling the newInstance method on the class. The static method XMLEventFactory.newInstance is then used to create a new factory instance. This factory references the javax.xml.stream.XMLEventFactory property to instantiate the factory. The algorithm used to obtain the instance is the same as for XMLInputFactory and XMLOutputFactory but references the javax.xml.stream.XMLEventFactory system property.
[ April 20, 2007: Message edited by: Joseph Sweet ]
Writing technical documentation is hard. Writing something that's complete but concise is harder. Writing something that's simultaneously pleasant to read is harder still. Not many people master the skill.
And while it's easy to take a single paragraph, work it for a while, and come up with something better, try doing it for the whole tutorial you're looking at. Then think about the amount of time it took you. Then find out how much technical writers make, and what their workload is like, and do the math. See how well you could compete! Remember that those Sun tutorials aren't written for fun -- somebody's getting paid to do a job.
Now books -- books are a little different. Books are a labor of love, because so few programing-book authors ever get paid a fair wage for their time. I'm less forgiving of badly written books (my own excluded, of course )
We take the easy way out by unabashedly declaring that we write teaching books. We make no attempt to create reference material. This allows us to be informal, and it allows us to not worry about corner cases. It seems to me that it's often those pesky corner cases that can turn an otherwise easy-to-describe concept into a real bear.
So my vote is either write reference material or write learning material - but do only one of those at a time.
I have really brought a lenient case from the Sun JEE tutorial. I do not consider myself as a dumb (maybe I am though), but so many pages there I have happened to read over and over and ask myself, "what the heck are you trying to say???".
They lose me when they use a term that can be one thousand things (depends on the context), don't bother to explain the context (because have to put it all in one page), then add another term that can be one thousand things, and another one.... and it's ok if you know the context, BUT HEY, I DO NOT YET. You have to help me to see the one picture that you have in your mind, not a tree of millions of possible pictures.
It's not such a big deal to write a text, that someone will understand if he ALREADY KNOWS the subject.
But guys, if I knew that stuff I would not try to go though that tutorial.
The art is to write a description that will transfer the reader from a state of "I don't have a clue" into a state of "Huh, now I got it".
The Sun tutorial is awful because it rarely does so (many other books are just the same). I had to leave it aside so many times, go look for better explanations in other places, and then come back and finally understand what they were trying to say.
I think it takes a very humble and patient personality to write a text that teaches. You have to forget how knowledgeable you are, and help someone else to climb upstairs.
Yes, if it takes 10 pages to explain a matter right, then don't try to put all the headlines into a single page, and say "go, eat it".
Back when Sun Ed was really, really busy teaching Java, the Java course instructors dubbed the kind of writing you're talking about as:
"Clear only if known"
I think this is a typical feature of technical writing of all kinds. When I was first learning Java I used to read a magazine article, then when I got to the end I would realize I didn't know what the heck it was about. After re-reading it a couple of times and tinkering around with some code, I would eventually get it.
Originally posted by Joseph Sweet:
I had to leave it aside so many times, go look for better explanations in other places, and then come back and finally understand what they were trying to say.
Now I'm reading the Websphere Management and Configuration Guide. It's about 950 pages and most of it is irrelevant to my needs. But I don't know which parts are relevant until I look at them. And when I got to chapter 3 it suggested I should have already read Planning and Designing for Websphere (300 pages) and the Websphere Migration Guide (350 pages), so I'm doing that. I'm still not clear on when I should federate a node (or is it a cell I'm supposed to federate) or on what a profile is for, but eventually it will become clear.
This quote of yours, "It's not such a big deal to write a text, that someone will understand if he ALREADY KNOWS the subject." brings to mind the marketing blurb from Head First books:
Tired of reading Object Oriented Analysis and Design books that only makes sense after you're an expert?
The best part about that blurb is that it is so true! (Or maybe thats the worst part about it?)
[ April 24, 2007: Message edited by: Michael Farinha ]