Moved. See All new content goes to the new site. This is a legacy, and will likely be dropped five years after the last post in Jan 2023.

Tuesday, February 16, 2021

The "The reader won't know what that means" Comment

I have to admit, it's very difficult to respond to this comment. I have to fight down the urge to say things like "The Reader is not an idiot," or "At some point, we have to assume they've seen a computer before."

AFAIK there's little or no useful data data on how much background people buying technical books have.

Subjectively, it seems like folks who leave the most comments -- the noisy few -- seem to balk at chapter 1 things, write a bad review or blog post and move on. 

It appears they expect to see chapter 1 reinforce their impressions of their own skills and present the things they -- individually -- don't yet know but tend to suspect. It needs to involve minimal surprises, and no forward references to later chapters.

I wish I could write like that.

But I can't write like that. I feel the need to assume that some readers actually do know some things and want the forward references so they can skip around.

I feel the need to assume readers have seen another programming language and have worked through a tutorial or two. 

I may be wrong. It may be true that most readers buy exactly one book and expect this to be an introduction to computers, languages, and computer science. If so, I need to learn how to cater to their needs.

I may be right. People may have background in at least one language and buy multiple books. If so, I don't think "the reader won't know what that means" is really a helpful comment. 

For some technical concepts, I like to rely on inductive definitions. Rather than fussy formalisms, I think it's helpful to use concrete examples. If there are weird edge cases or seeming contradictions, a fussy definition may be helpful, but not as a starting point. The comment "the reader won't know what that means" prior to the first example is a teeth-grinding thing. Yes. They won't know. That's why the rest of the paragraph is an example so the reader will know what it means.

The good news is the reviewers are reading very closely and splitting each hair. I am eternally grateful for the opportunity to grind my teeth in exasperation.