aspose file tools*
The moose likes Bunkhouse Porch and the fly likes Windbags 2 Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Books » Bunkhouse Porch
Bookmark "Windbags 2" Watch "Windbags 2" New topic
Author

Windbags 2

Joseph Sweet
Ranch Hand

Joined: Jan 29, 2005
Posts: 327
Human right-to-the-point style (taken from: me):

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 ]

We must know, we will know. -- David Hilbert
Ernest Friedman-Hill
author and iconoclast
Marshal

Joined: Jul 08, 2003
Posts: 24187
    
  34

Note that the book excerpt, although it does repeat itself a bit, says quite a bit more than your summary. It explains something about how the instance will be created, and refers you to other sections that might include more detail.

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 )


[Jess in Action][AskingGoodQuestions]
Bert Bates
author
Sheriff

Joined: Oct 14, 2002
Posts: 8829
    
    5
My two cents is that most technical authors, somewhere in the back of their minds, are trying to write stuff that can serve to teach AND to refer to. IMHO that's a bad idea!

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.


Spot false dilemmas now, ask me how!
(If you're not on the edge, you're taking up too much room.)
Joseph Sweet
Ranch Hand

Joined: Jan 29, 2005
Posts: 327
Thank you for your input.

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".
Bert Bates
author
Sheriff

Joined: Oct 14, 2002
Posts: 8829
    
    5
It's really funny that you would say that...

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"
Paul Clapham
Bartender

Joined: Oct 14, 2005
Posts: 18650
    
    8

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.
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.

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.
Michael Farinha
Greenhorn

Joined: Jun 16, 2006
Posts: 26
Hey Joseph,
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 ]
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Windbags 2