Misa (41) [Avatar] Offline
#1
Some thoughts:
- There is no information on how to download Express, install Express, and create a simple program! It's just bewildering that you have provided details on encryption, routing and testing, but nothing on how to create a "Hello world!" example. I guess that will eventually be in Chapter 2, but there is no chapter 2 at the moment. As things stand the book is close to useless for someone who does not know anything about Express.
- Many of the code listings are poorly formatted. For example, listings 4.4, 4.5, 4.6, 4.7, 4.9, 4.10, 4.11, 4.13, 4.24.
- You dwell on stuff that doesn't matter. For example, when discussing zip codes you state: "ZIP codes are five digits long (technically nine, sort of)". Well yes, but for a foreign reader who knows nothing about US zip codes this comment is unhelpful and confusing. Anyway, who cares? Just state US zip codes are five digits; that is all that is necessary. There are other examples of this unnecessary chatty digression on irrelevant minutae throughout the book.
- You have cleaned up the book with respect to some potentially offensive/inappropriate terms, but I urge you to remove all references to "Turd" and "barack_obama". You may think using "Turd" is amusing, but others may find it coarse and offensive. You may think Barack Obama is a great guy, but I am certain that some in your worldwide audience will have a different view. Use neutral terms in all your examples. Words and concepts that may offend or irritate are counterproductive, disrespectful to your readers, and convey an unprofessional tone.

I am really trying to like your book. Your down-to-earth enthusiasm is really refreshing, and it shines through on every page, but I see some major issues with the book as it stands.
Evan Hahn (70) [Avatar] Offline
#2
Re: Feedback for the V04 update
Thanks for your feedback!

The first two bullet points will be fixed soon. I'm doing a big rewrite of the first few sections of the book and all of that will be present. The malformed code listings will be fixed as well; we've had a few formatting problems here and there.

As far as the rest, I think I'm going a bit too far trying to be conversational and that can distract from what I'm really trying to do, which is teach you about Express. I'll go back and fix those.
BobCochran (92) [Avatar] Offline
#3
Re: Feedback for the V04 update
Hi Evan,

I have quickly skimmed the first pages of V04, and I agree with the points that Misa is making. I really need a tech book that explains how to use Express and Jade and perhaps some of the other templating engines. I would like to show the book to others and know that the content is not offensive. I would like younger folks to read your book and focus on getting results with Express.

So many thanks

Bob Cochran
Magnitus (70) [Avatar] Offline
#4
Re: Feedback for the V04 update
>You may think Barack Obama is a great guy, but I am certain that some in your worldwide audience will have a different view.<

Not to disgress too much, but I believe he was always more liked abroad than domestically. If I'd worry about it being received poorly, it would be mostly from very polarised Conservative U.S readers.

Overall, though, I don't think Obama is that controversial a topic for an example in a book unlike, say, Adolf Hitler.
Evan Hahn (70) [Avatar] Offline
#5
Re: Feedback for the V04 update
I think the safe thing is to change it to a name that nobody will have any opinion about, which I've done. You'll see that in the next MEAP and the final version of the book.