ASP.NET Core 2 and Angular 5: the Broken Code Myth strikes again

I would like to thank everyone who supported me buying my third book - ASP.NET Core 2 and Angular 5, which already sold more than 2000 copies and is still on top of all major online stores. I'm also pleased by all the positive reviews I got so far, with an average between 4.1 and 5.0 stars between the Packt Publishing website and the various Amazon stores worldwide.

However, just like I did with my first book, in this post I will mostly talk about the negative reviews I got, trying to figure out the reasons and saying my point of view about it. At the moment (13 January 2018) there's only one of them, but I expect more of them to appear in the following weeks/months, when the time will take its toll and the book printed code will slowly become outdated.

Not surprisingly, the single negative review I got so far falls straight into the "broken code myth" category which I firstly introduced here and then framed in this dedicated post: to quickly recap it, we're talking of people saying that "the source code is broken", "the samples doesn't work", "there are a lot of compile errors" and so on. These kind of reviews are fairly common for programming books filled with printed source code, where a number of different things can happen: code errata from the author, a newbie reader who doesn't follow the book, a wrong edit by the editorial reviewer, a mistake from the technical editor, a typo from the layout editor, a major update of the development framework with breaking changes, and so on.

Anyone who works in the industry - and most competent readers as well - perfectly knows that the "printed" text goes through a lot of changes and rewrites. Now, when we're talking about a standard book, or even a technical book, it doesn't really matter: you get to read Ngnix instead of Nginx, which is definitely not a big deal. That's not the case for a programming book, where even a single typo, error or misplaced line of text made by the editors OR by the reader WILL prevent the source code from compile - possibly driving the average reader to an utter journey of frustration and distress.

First Attempt: GitHub

Although the aforementioned concept is rather simple to understand, I must admit that I highly underestimated the impact it would have had on some readers when I wrote my first programming book: I made the huge mistake to think that releasing a GitHub repository containing the whole book's source code and having its URL written on the book itself would have been enough. That way, whoever had problems with the book code could easily find a solution by checking the updated code on GitHub. Simple enough, isn't it?

It turned out that I was wrong, at least for a fair amount of people, who just ignored the GitHub link & repo altogether and started whining about the book code being either broken, not working, not updated and so on. No matter how hard I tried to demonstrate the actual fact that there was a perfectly-working, freely-available GitHub repo containing the exact same source code printed in the book: the broken code myth still held its way for many of them, despite all logical attempt, against all irrefutable proof... To the point that I even started to think that some reviewers were trolling, or - even worse - purposely write fake negative reviews to down-rate the book, maybe to favor someone else.

Here are some valuable examples:

• Complete waste of money!!! , by Rogue BJJ Prof on Feb 27, 2017 - Basically claims that none of the book samples actually works, entirely ignoring GitHub - which had 100% working code.
• Sample code/project not working , by Mohammad on Oct 13, 2017 - Written 12 months after the book being published (and more than 40 Angular updates released , not to mention two major ASP.NET Core rewrites) to point out how everything in the book is now outdated: nice catch, Mohammad! It's also interesting to see how the user only wrote 6 reviews, all of them being programming books which he either gave 5-star or 1-star rating: no mid-ranges there, each one of them is either a masterpiece or a pile of junk.
• One Star , by JayLuke780 on Oct 17, 2017 - This one-liner is one of my all-time favourites: "Dated wish i knew before buying". Same school of Mohammad, but he had only 2 programming book reviewed... And here comes the fun: he bought both of them the same day and gave them both the same identical review! Needless to say, the other book is also one-year old: it seems that the poor James Chamber is to blame as well, since he also didn't thought to warn that guy that time passes by. He wished he knew...

• Another worthless cash grab technical book , by Amazon Customer on Feb 4, 2017 - Another love declaration by a nameless Amazon Customer, who even warns other users that most of my book's reviews are "inflated con": I personally think he's right and that he should definitely be the one to be trusted instead, since he had reviewed a wallet (3-stars) and my book (1-star) in the whole course of his Amazon career. He also undergoes through a deep analysis of the book by saying that "nothing will work", which basically means that he's among those who skipped or ignored the GitHub repo; that doesn't stop him from warning people to not waste money on it, which in my opinion is a great advice - for those who cannot deal with programming books.

Long story short, despite my efforts to provide my readers with working & updated source code despite the inevitable aging of the printed pages, I failed to reach the heart (and/or the mind) of some of them. As you can see by looking at the comment sections of these reviews I tried to address them, always in a polite and respectful way, by asking additional info: where that "broken code" exactly is? Can you reproduce the issue on the GitHub code as well? Can you show me the differences between the GitHub code and the printed book code?

I honestly thought that, being the author and having written the code myself, I definitely could help them. Guess what? None of them cared enough to answer me. Not a single one. I wrote more than 10 replies to these comments and the only answer I got was this sweet one-liner by the aforementioned Rogue BJJ Prof - who ignored my comment to his review and answered to this other one, which was addressed to another guy (third comment from top), which is basically a reprise of his previous review:

The code in this book simply doesn't work. The information is already out dated.

As simple as that.

Regardless of the reasons, I couldn't do anything else than learn from that lesson, hence I wrote the post that would've inspired the Broken Code Myth theory and treasured the experience for future times.

Second Attempt: GitHub + Disclaimer

When I published my third book I was fully aware of the fact that the GitHub repository alone would not have been enough for those readers. Not only because they would've just skip that and/or been unaware of its existance, yet also because I needed to take care of a lot of unexpected scenarios that had manifested themselves in the reviews: those who want to upgrade everything withoug reading the changelogs; those who purchase a 1-year old book expecting it will work out of the box; those who think that the code doesn't work because "the author didn't  check it properly" thus ignoring the fact that there's a whole team of technical reviewers and testers that will give the OK / KO status, with names & roles written on the book's preface; those who think that if the code on GitHub works and the printed code contains errata the book is garbage or unusable or broken, thus ignoring the fact that the GitHub repo is actually part of the book and it's meant to overseed/overwrite/patch/fix/update it; and so on.

All these singularities brought me to write a dedicated paragraph in the book's Chapter 1, which I called Disclaimer - do (not) try this at home and also contains the first installment of the Broken Code Myth theory. The full abstract is available here, yet it can be useful to highlight some relevant quotes:

This book will make an extensive use of a number of different programming tools, external components, third-party libraries and so on. Most of them [...] are shipped together with Visual Studio 2017, while others [...] will be fetched from their official repositories. These things are meant to work together in a 100% compatible fashion, however they are all subject to changes and updates during the inevitable course of time: as time passes by, the chance that these updates might affect the way they interact with each other and the project health will increase.

Which basically mean: please understand that we're building a tower with independent bricks that will inevitably change during time, while the printed book won't: either learn how to deal with that or think about doing something else.

There's no way this book can even attempt to hit the shelves unless it comes with a 100% working source code, except for few possible minor typos that will quickly be reported to the publisher and thus fixed within the GitHub repository in a short while. In the unlikely case that it looks like it doesn't, such as raising unexpected compile errors, the non-novice reader should spend a reasonable amount of time trying to understand the root cause. Here's a list of questions they should try to answer before anything else:

• Am I using the same development framework, third-party libraries, versions, and builds adopted by the book?
• If I updated something because I felt like I needed to, am I aware of the changes that might affect the source code? Did I read the relevant change logs? Have I spent a reasonable amount of time looking around for breaking changes and/or known issues that could have had an impact on the source code?
• Is the book's GitHub repository also affected by this issue? Did I try to compare it with my own code, possibly replacing mine?

Which basically mean: do your best to not be the guy who brings his car to the mechanic whenever the fuel gas is empty. If you are - or you want to become - a software developer, you cannot act like any unskilled service desk operator who whines on the IT office every time its PC raises an error of any kind. There are a bunch of basic things you can and should do before freaking out and rage-write an unfair Amazon review.

I honestly thought that these concepts would be enough to help everyone undestand how to handle not only my book, but also any programming book: I really did. Surprisingly, it wasn't: in spite of such effort, the Broken Code Myth syndrome still took its toll on a single reviewer (so far). This time I'll quote the review in its entirely because I think that it's a perfect example for proving the whole point:

I realize that writing a technical book is not easy. However

by tech-reader on January 12, 2018

 

The author goes on a rant, subtitled, 'The broken code myth' on page 21, in which he attempts to persuade one that if the code won't compile, its not his fault. WELL, this code is a mess. If you work through the project presented, precisely as described, you will run into no end of compile time and run time errors. Now, if you download the code from github (corresponding to the chapter you are working in), you will find code that compiles and runs without issue. If you compare this to the code presented in the book, you will find it does not match. The book is completely frustrating. I have probably read over 100 programming books. I realize that writing a technical book is not easy. However, making sure that the code presented in the book works correctly is not the hard part.

 

That being said. In the authors defense, he does know the subject matter and presents the concepts fairly well. So, if you are NOT going to work the examples, and are just looking for the concepts, maybe this will work for you. I would avoid it though. These technical books are far too expensive to spend your time being frustrate instead of coming up to speed quickly on a complex subject.

If there would be a Broken Code Myth paragon, it would be tech-reader.

Not only he did read the disclaimer, he also managed to reach the GitHub repo and found the working, flawless code! However, despite all that, he still went for the 1-star review. He couldn't care less of the online code, he still chose to struggle with the printed one; he doesn't want to hear that the GitHub code and the book code are coming from the same source (GitHub first commit = book code), and - most importantly - refuses to accept the fact that the online source is there to get the updates, fixes and maintenance the printed one can't possibly receive. Obviously he's also certain that any other reader will adopt his way of thinking, thus spending their time being frustrate instead of... simply pull the GitHub code and deal with any typo, errata and compatibility issue in a matter of seconds.

And here's the icing on the cake: despite his claims to have probably read over 100 programming books, tech-reader only wrote this single review on Amazon.com. Of course there could be a lot of explanation for that: maybe he did purchase these 100 programming books on local stores in paperback editions, which could explain his aversion for GitHub repositories; or he could've created a brand-new account for privacy reasons; it could even be a fake account, part of an evil scheme of a competitor publisher who hates Packt Publishing, ASP.NET Core, Angular and/or myself. I guess that we'll never know. [EDIT: I was wrong on that too - it seems that Amazon.com solved that riddle - read below for details]

However, here's the answer I gave to the review:

Hello and thank you for purchasing the book.

 

In your review you're clearly saying that the GitHub code works and that the concepts are fine: there would be no reason for a 1-star review then, expecially considering the fact that the 'broken code myth' paragraph you've mentioned is clearly written with the sole purpose to prevent any frustration by making the reader aware of the fact that there is a free-to-use GitHub repository available - where he'll find not only the updated and error-free source code, yet also a ton of useful info that couldn't fit in the book, not to mention first-hand help from the author and fellow readers in case of erratas, breaking changes and so on.

 

If you've really read 100 programming books you should be aware of the fact that the "printed" source code goes through a lot of changes and rewrites - author, technical editor, layout editor and so on: typos and erratas are fairly common when undergoing such process, that's precisely why we provide the reader with a GitHub repo - and tell him to go there a number of times throughout the book - so that he'll not "spend time being frustrate". Ignoring such advice and just "being frustrated" by the stone-written printed source code basically means doing the opposite of what the book actually says: the 'broken code myth' patient zero, who ignores (or not consider) GitHub and stubbornly sticks to the printed paper: the frustration is coming from such mindset, not from the erratas. To counter that, I sincerely hope that the editors will eventually allow the authors to get rid of any printed source code from their books in favor of freely available online repositories, being them (and their usage) a must for any developer these years.

 

That said, it's also worth mentioning that the differences between the GitHub code and the book code are minimal (3 erratas discovered so far, involving very few lines of code, all fixed by the author within 24-72 hours): the "no end of compile time and run time errors" is a huge overstatement that anyone can dispute by looking at the GitHub history, the GitHub first commit being identical to the book code.

 

I sincerely hope that you'll understand my reasons and edit your review accordingly, it really seems like you just want to down-rate the book and I honestly don't understand why - after all the hard work being spent and the amount of working source code which you even acknowledged.

I chose to stick with the diplomatic approach there: he still bought the book and thus he deserves my respect; at the same time me, I feel like my work, my editorial staff and the publisher also earned some, expecially considering all that everyone did to mantain the GitHub repo and promptly answer to all the issues opened by the readers so far. I couldn't do much more than rephrasing the same exact concepts I already wrote on book page 21, which couldn't

UPDATE: It seems like the review has been deleted from Amazon.com, probably because the staff thought it was a fake negative review; I feel that they might be right, since - like I said above - tech-reader account had no previous history or activities other than that single review. Luckily enough I managed to pull it off from my browser's cache and take a screenshot, so that everyone can read it:

Was it really a negative review scam or a legitimate case of Broken Code Myth syndrome? Feel free to give your shot in the poll below!

Epilogue

Writing a programming book is no easy task: the author will have an hard time dealing with a massive amount of code, but the most difficult part will be ensuring that the reader will be able to properly copy, use and/or update it. There are a number of things that will make it way more difficult than you might imagine: my public GitHub experience (here and here) can easily demonstrate that, 9 times out of 10, what initially seemed to be a book issue was actually a different kind of problem - most likely related to the reader's environment settings. However, there are also typos, book erratas and a number of issues brought by frameworks, tools, libraries and components major updates that you will have to handle, not to mention the readers who will actually need some help: GitHub (or other similar platforms such as BitBucket) are probably the best way to deal with these things, as long as you'll do your very best to drive your readers there.

That's precisely why, like I said in my answer to tech-reader which unfortunately has been deleted with his review, I hope that the editors will eventually allow the authors to get rid of any printed source code from their books in favor of these online repositories, being them (and their usage) a must for any developer these years.

After all this wall of text, here are some useful suggestions I could possibly give when dealing with programming books:

• If you are (or plan to become) an author, publish your code online and point your readers there, then do your best to mantain it.
• If you are a reader, do not rely too much on the printed code and use the online repository that comes with the book to get the updated sources: if the book does not provide you with that, consider to return it and get a better one.
• If you are a reviewer, feel free to write whatever comes to your mind in your review: however, immunizing yourself from the Broken Code Myth syndrome should be a top priority if you really want to give a worthy advice to your fellow readers.

Print Friendly & PDF Download