English: it's so easy to mean something you didn't mean to mean

[Ralph Cook]

Without even being mean about it.

On page 178 of "Head First Servlets and JSP", step 4 in a bunch of steps of how a Servlet Event Listener and attendant classes do their thing, is step 4:

"Container gives the ServletContext references to the name/value parameters"

Naturally all of US understand what is meant. But someone struggling with the concepts in the first place can end up thinking -- "What ServletContext parameters do they mean? Why is there more than one? What would the name and value parameters do with such a reference? I had better read the whole thing over again from the beginning".

English doesn't have grouping operators, you see -- if we had some way to group "references to the name/value parameters" as distinguished from "ServletContext references", then it would be clear what references were meant.

It appears at least one other time in the book -- a part of this same sequence appears in an earlier set of sequences. If I had a search function on my analog copy of the book, I'd look it up.

rc

[Bert Bates]

Here's another one we struggle with:

"You must implement the method in the subclass unless the subclass is also abstract."

vs.

"You must implement the method in the subclass unless it is also abstract."

Until very recently, we thought we were doing everyone a favor by not using 'it'. We thought that repeating 'the subclass' made everythinh clearer. Recently we attended a talk given by a writer we both respect... he made very compelling arguments that 'it' is far clearer than 'the subclass'. His argument went something like this:

'it' is like a reference to an object, it's very clear that there's only one object being discussed. If you say 'the subclass' a second time, it might be indicating a second instance of 'the subclass'.

Hmmm... we'll just keep practicing... and certainly making lots of mistakes

[Michael Ernest]

How about 'a concrete subclass of an abstract class must implement all of its abstract methods'?

[Bert Bates]

Hmmm... I could take that two ways too That could even fall into the category of technical writing that we try to avoid... 'clear only if known'. In other words, if you already know how it works, the sentence is much clearer than if you don't (already know how it works )

[Michael Ernest]

I'd have to wonder how you're presenting the abstract class if 'concrete class' might be a forward reference....

[Bert Bates]

I'd guess that this sentence caught us in 'mid-reference'

[Michael Ernest]

Originally posted by Ralph Cook:

"Container gives the ServletContext references to the name/value parameters"

Naturally all of US understand what is meant. But someone struggling with the concepts in the first place can end up thinking -- "What ServletContext parameters do they mean? Why is there more than one? What would the name and value parameters do with such a reference? I had better read the whole thing over again from the beginning".

Innnteresting problem. I'm with you on the first question. The next two sound like the emerging anxiety attack I have seen all too often when a students feels something is wrong: "Wait. I don't understand this. Why doesn't this make sense? What more don't I understand? Is the book wrong? Am I wrong? Are they trying to trip me up? Will I be exposed for the fraud that I am? Oh no, they're not taking me down that easily!"

A lot of times a tech writer comes across spec information or other text en pointe that is so obtuse, or wrongly thought and accordingly expressed, that while the concept seems clear, how to share or better express it is not.

It's relatively easy to fix a sentence that doesn't convey a clear idea quite right. Having to fix a murky or broken idea to get a sentence right, that can be a monstrous timesink. We often smooth these burrs in the mind and pray in the name of deadlines it's good enough.

Hijack! --

I'm going through an ugly variant of this problem right now with some courseware for a certain nameless company on the topic of Solaris performance management. There's lore, there's misconceptions, there's stuff so wrong as to overwhelm the pain receptors, so that a person can't actually read it. Here's a classic paragraph:

Application threads provide a better solution that improves the performance of the system without using real-time processes. A bound thread with its LWP set into the real-time class has less impact on the system. In addition, a bound thread can segment real-time and normal tasks more easily than an unbound thread.

I don't know what the author meant to say, but I was able to find the 3-4 pages of source material they used, or perhaps were told about in the middle of a supermarket. The perverse thing is, I can see how they got to this place from what they might have read. There was more than enough "clear only if known" schmeer in the presumed source. This short paraphrase merely ripped out enough of the white-noise qualifiers and detail that what was left ultimately condensed into a jumble of contradictory or non sequitur statements.

It's an extreme and wretched example, but extremely and wretchedly a similar problem: at what point can you be sure your reader will follow you over a bump in the text rather than freak, start over, and see if the bump is made clearer by repetition? When might your reader be numbed by a clear but tedious explication of every reference? It can be a difficult balance to strike, especially when you have to coin expressions for ideas easy to capture on review, but not so easy to get the first time around.
[ August 27, 2005: Message edited by: Michael Ernest ]

[Ilja Preuss]

Originally posted by Michael Ernest:
How about 'a concrete subclass of an abstract class must implement all of its abstract methods'?

'a concrete class must implement all inherited abstract methods'?

[Michael Ernest]

Originally posted by Ralph Cook:

"Container gives the ServletContext references to the name/value parameters"

Check it out, man, the container? Be dishin' client-side 4-1-1, you know that. And the ServletContext? There to receive, baby! There to receive.

It is the responsibility of the web container to transmute environment information from the browser into a set of environment information suitable for use within a servlet. The web container uses a ServletContainer instance as the means for passing this information along.

Browser request information -> web container -> ServletContext. It's a game of telephone.

...

Seems to me you have to back up and explain a typical browser request, what a web server does with it, and how ServletContext gets a useful muck of this stuff and provides an interface for drawing it out. In other words, if your average SCWCD candidate doesn't know what happens in a web server that does not support servlets, they can only take what you say on faith to begin with.

[Ralph Cook]

Originally posted by Bert Bates:
Here's another one we struggle with:

"You must implement the method in the subclass unless the subclass is also abstract."

vs.

"You must implement the method in the subclass unless it is also abstract."

Until very recently, we thought we were doing everyone a favor by not using 'it'. We thought that repeating 'the subclass' made everythinh clearer. Recently we attended a talk given by a writer we both respect... he made very compelling arguments that 'it' is far clearer than 'the subclass'. His argument went something like this:

'it' is like a reference to an object, it's very clear that there's only one object being discussed. If you say 'the subclass' a second time, it might be indicating a second instance of 'the subclass'.

Hmmm... we'll just keep practicing... and certainly making lots of mistakes

Hmmm -- "Unless the subclass is abstract, it must implement the method". You could even add "(and all its other methods)", if you think the reader needs another reminder about abstract classes.

[Michael Ernest]

I re-glossed a couple HF books with this thread in mind, and saw how much stupider my intentionally stupid paraphrases became once they got cold, I started to think more about the disconnect between the way programming languages work and the means we have to talk about them.

Most closed technical systems, such as a programming language, cannot be designed with ease-of-understanding in full view. That's what makes them 'technical,' eh? But that's ok in thr short term, because specs are good enough for experienced practitioners, early adopters, and other sad but intense geeks who run at new technology as fast as it runs at them. For those folks, learning is a collision sport. When I saw such people in a class, it was usually their intent to see if I had found some nugget of insight they hadn't got to yet.

For others, who need these skills but have no solitary passion for acquiring them, there is a more interesting way to develop connection and help them explore (and yes, that's the HF premise already, but hear me out). It's more interesting to me, anyway, as an educator. But if you look at the HF testimonials by some early adopters, you'll read between the lines a tinge of envy: why can't learning be made like this for them? (No time for guys like you! sorry!) It's more fun, engaging, stimulating to cross-think and associate and relate than it is to read, try, learn, repeat, no matter how fast anyone can do the latter.

That said, when we come across concepts for which any human-relatable analogy or metaphor feels labored, there are few options. One might be to say the figuratively lame thing you could think of. This choice, we know when we see such examples, is foo. Another might be to repeat the spec, more or less. You're then stuck with 'implement' and 'abstract' and 'concrete' and ifs and thens, and ugh: I'm learning again, aren't I?

I wonder if the attendant misunderstanding that lauched this topic comes in part from this sudden replacement of vivacious language, bold images, etc. with spec language. The disconnect isn't necessarily in the statement itself -- or maybe it is -- but in the rhythm, the voice, the unities of the text.

There will always be dry patches in a book like this where crossing certain dry patches is what it is. There's not much you can do without going rather far afield to sustain voice.

That said, it's a decent measure of the approach so so few examples of this crop up. After thinking through this case it occurred to me just how well-sustained the approach is in the books I've seen. Not an easy thing to do. The sentence that started this all, has become to me an exception that reinforces the rule.

[Ralph Cook]

I don't think it necessarily comes from going back to the 'spec' language. I think some of it is, in fact, unavoidable; one must understand the terminology attendant on any technical subject (on any subject?) to handle additional documentation and to refer to the concepts and entities in that subject concisely.

I just think this sort of thing happens to any writer because any writer comes at the subject with his own viewpoint and set of assumptions, and if they don't match the reader's well enough, then there is naturally a disconnect between "the toss and the gulp". And this particular example just resulted in a wording that can be taken another way, it's not a big deal.

rc

[Bert Bates]

For my part I find this to be an interesting thread. I'd rate Kathy a solid writer, and I'd rate myself a poor one. We're hoping that the other elements we bring into our books is more important than our ability to craft wonderful sentences. That said, we're both working on becoming better writers, and this kind of duscussion is useful. The other thing is that it seems to me that writing an 800 page technical book is kind of like writing a 30,000 program... it's bound to have some bugs so I'm not too upset when someone finds a little 'bad code'. We've worked hard over the last few years to reduce errata, and I think we've made some progress there, but again I don't see it as a black and white situation. These books will never be bug free, it's just about getting the bug count down to a level that allows the rest of the book to work for everyone.

In any case, no offense taken here, and certainly none meant, and thanks for all the input.

- Bert