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 )
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.)
Joined: Jan 29, 2005
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".
Joined: Oct 14, 2002
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:
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.