Cristian Vasile Mocanu (2) [Avatar] Offline
#1
I am currently reading MEAP version 9 of this book (I'm on chapter 3), and it's a pain to read.

The information is good, but there is WAAAAY too much repetition and unnecessary text.
I get the distinct impression that the book can be reduced to at most half the current size, without ANY loss of information. Some examples:
- the information the the text is repeated multiple times throughout the book
- the information in the main text is repeated in the caption to the diagrams
- navigation boxes: these are largely repetitions, not only of the table of contents, but also of other navigation boxes and of the main text. If I want to navigate, I'll use the table of contents, that's what it's for. Not only that, but the boxes are highly distracting, interrupting the flow of thoughts (what was I reading about?)
- other boxes, like "IMPORTANT", e.g. "A requires directive contains a module name and tells the JVM that the
declaring module depends on the one given by the directive." This point is made again and again in the main text. Why the repetition? Just the "IMPORTANT" box would have been enough. Or put the "IMPORTANT" box in a sidebar, and tell in the introduction that the sidebar is only needed as a reference, not if reading the book from beginning to end (so we know it's safe to skip it). In any case, please DO SOMETHING about the repetition!
- another example: "The descriptor holds all the information needed by the module system to create a run-time representation of the module. This means that all properties an individual module has are represented in this file and, consequently, many of the features that are discussed throughout this book have their counterpart in there, too.". Do you see how the second sentence doesn't tell me anything that I didn't get from the first one? Not only that, but the repeated sentence is twice as large, so the information is inflated 3x. This is not an isolated example. This is the norm smilie
- another example: "So a module descriptor, a module-info.class , is all we need to turn any old JAR into a module?! Great! That begs the question, though, how exactly we can create a descriptor. As the file ending .class suggests, it is the result of compiling a source file". See how the last sentence makes the previous 2 superfluous? This is repeated AGAIN in the "DEFINITION" box that follows. That's 3-4 times extra text that is only useless repetition.
- etc., etc.

All these makes us waste a lot of time getting the information that we need. I will spend at least double the time for no additional information, because I can never be sure if what I will be reading is repetition that I can safely skip, or important information, that I don't want to skip.

Because of the repetition problem, the book wouldn't receive from me more than 2 stars out of 5, even thought the information is probably 5 stars.
It's just THAT MUCH PAIN to read.
Honestly, I would have probably been more benefited to read the JEP documents: just as much time spent, but much more information gained. As a bonus, they are free.

As it stands, I can't recommend the book to a friend. I will only be able to warn them about this problem.

This is not the first time this happens with a Manning book.
I have "Dependency Injection" by Dhanji R. Prasanna. It has half a page explaining what is a transaction. Really? In a dependency injection book?
Also, if I remember correctly, I had this problem (unnecessarily increasing the page count) with "JSF in Action".

Those 2 books made me avoid Manning books for quite a while.

I think Manning editors would do well to keep the audience in mind.
Would a junior read a book dedicated to java modules, or a generic java book that includes information about modules?
Obviously, most developers reading this book are seniors.
Senior don't like to waste time reading repeated text.
Actually, I don't think anyone (seniors or not) enjoys wasting their time reading the same information 2-4 times.
If you want to help people remember, exercises are much more effective (proven scientifically) and they are not a pain to do, like reading repeated text again and again.

Remember, you are selling information, not pages. More pages where fewer would be enough, DECREASE the value of the book, as will doubtlessly be seen in the negative reviews.

To understand how a book should be written, take a look at "Java SE 8 for the Really Impatient":
- no repetition
- no unnecessary information
- the information is driven to long term memory by the exercises at the end of each chapter.
And it manages to cover new Java 8 features (and Java 7 in an appendix) in 238 pages.
It's an excellent example of how all books should be written.

Sorry for sounding as complaining, but it really is very painful to read this book, and Manning editors need to know about this.

Not sure who's at fault for the repetition (the author(s) or the editor(s)), but whoever he is, he needs to read "The Elements of Style" by William Strunk Jr. and E. B. White.
Nicolai Parlog (7) [Avatar] Offline
#2
Hi 96301, smilie

first of all, thank you very much for your honest feedback! As the author, it's of course not exactly a pleasure for me to read it, but it is still valuable.

I can understand your impression of the book being repetitive. You're definitely going to reread a lot of things you already know if you read it cover to cover over a short time span and have a good memory. Those traits make you pretty much the ideal reader, but by Manning's experience that sets you apart from most of the audience. Apparently, most readers work through their books in fits and starts, leave certain parts out, and start reading at random whichever chapter or section interests them. Those readers benefit from repetition and references as it makes it easier for them to remember what they read some weeks ago or shows them which other mechanism than the one they're reading about they need to look at first. It also helps if using the book as a reference later.

Following that logic there needs to be some repetition, but the question of how much is of course up for debate and comes down to a trade-off between boring readers (like you) or loosing readers (like those who read less intensely). I hope we struck the right balance across the audience.

Before I address some of your specific criticisms, I want to encourage you to read past the first part (in case you haven't). The first part covers the basics and is very interwoven - the latter parts still repeat some facts from the first (maybe boring you again), but contains much less cross references, so it may be a better read. If you find the time to dip into the other parts, I would be glad to hear your feedback on them.

Now on to some specifics:

the information in the main text is repeated in the caption to the diagrams


True. That's on purpose for people who skim or skip the text in favor of diagrams.

navigation boxes: these are largely repetitions, not only of the table of contents, but also of other navigation boxes and of the main text. If I want to navigate, I'll use the table of contents, that's what it's for. Not only that, but the boxes are highly distracting, interrupting the flow of thoughts (what was I reading about?)


The ToC tells you where to find something, but not how it connects to what you just read. The idea behind the nav boxes is to give you content-sensitive tips where to go next. Still, some like these boxes, some hate them. And I guess it will get worse in the final version of the book when they are no longer set apart by formatting and an icon and are thus harder to skip. I will look into reducing their number during final edits.

- another example: "The descriptor holds all the information needed by the module system to create a run-time representation of the module. This means that all properties an individual module has are represented in this file and, consequently, many of the features that are discussed throughout this book have their counterpart in there, too.". Do you see how the second sentence doesn't tell me anything that I didn't get from the first one? Not only that, but the repeated sentence is twice as large, so the information is inflated 3x. This is not an isolated example. This is the norm smilie
- another example: "So a module descriptor, a module-info.class , is all we need to turn any old JAR into a module?! Great! That begs the question, though, how exactly we can create a descriptor. As the file ending .class suggests, it is the result of compiling a source file". See how the last sentence makes the previous 2 superfluous? This is repeated AGAIN in the "DEFINITION" box that follows. That's 3-4 times extra text that is only useless repetition.
- etc., etc.


I get what you're saying, but I don't agree with the conclusion. The goal of this book is not to state facts - you can get them from the spec. The goal is to teach these facts by presenting them from different angles (the first example) or stringing them into a train of thought (second example), so that it is easier for people to follow. If you're a quick study, that might bore you, but most readers are not helped when each fact falls from the sky exactly once.

Honestly, I would have probably been more benefited to read the JEP documents


Yeah, maybe. They miss a lot of subtleties that the book covers, but they are definitely more to the point.

This is not the first time this happens with a Manning book.


Frankly, thank you for mentioning that smilie because it was indeed Manning's editing that pushed me further into considering readers that basically only read the section that I'm currently writing and to make sure they have all the critical information they need - hence the repetition.

Obviously, most developers reading this book are seniors.


That's not at all obvious to me and it is also not the target audience. The target audience is "reasonably experiences Java developer [3-5 years] who wants/needs to learn about the module system."

he needs to read "The Elements of Style" by William Strunk Jr. and E. B. White.


Went straight to my reading list. smilie
Cristian Vasile Mocanu (2) [Avatar] Offline
#3
Hi 96301,

Changed my display name - didn't even notice it was an auto-generated one smilie

Too much repetition
Since this happened with other Manning books also, I suspect this is something that needs to be addressed by Manning editors. If you can, please forward my concerns to them.

People reading in fits and starts
If you (and I include Manning editors here) want to make a book easy to remember, here are a few advices:
- repeated information: if the repetitions are close to each other, they are basically useless. The interval between repetitions needs to be increasingly larger. Lookup "spaced repetition" for additional information (and the science behind this)
- information that is simply repeated (passive reading) is much less memorable compared to asking questions or requiring people to solve exercises (active reading). Active reading will make the information much more memorable. Of course, the answers needs to be provided in the back of the book, to allow self-study.

If I were the author of this book, I would:
* remove the repetitions until the book is 50-75%
* replace the repetitions with:
** exercises
** asking questions (maybe in a sidebar) regarding concepts introduced in previous chapters
Kind regards,
Cristian