The Story Behind “100 Go Mistakes and How to Avoid Them”
thecoder.cafe
thecoder.cafe
I'm surprised the copy editor was more comfortable using git than using a web-based review tool to leave comments, especially given that she was reviewing a Go book and didn't seem to know what Go was.
How does that even happen? It seems bizarre that Manning had this copy editor at all.
I recently had a negative experience with Manning. I sent them an email saying that I'm in the process of writing a book, and I'm self-publishing it, but I was curious about the possibility of applying to Manning for a second edition. I asked whether they accept second editions after a self-published first edition and what document formats they accept.
I got back a form letter telling me that they'd rejected my proposal. When I followed up and said I didn't send a proposal but was asking preliminary questions, they told me that they understood I hadn't sent a proposal, but they were going off of the table of contents on my book's website. I guess they decided to pre-emptively reject me?
They also only said Google Docs as a document format, but based on this blog post, clearly they accept AsciiDoc.
I mean all mainstream word processing applications have a 'commentary' / 'review' mode where someone can leave comments and suggest edits.
This is pretty off topic but did you test how your book works on an E-Reader? I check a sample chapter and there where a lot of pictures and colors to distinguish information, this will probably not work very well on my Kindle.
The first few chapters, I've been primarily targeting web and not testing on e-readers. I figured that until I knew whether people actually wanted to read it, I should just focus on making the web excerpts look decent and try to avoid over-optimizing for web.
Now that the book is officially a go, the PDF version is a first-class citizen, and I'll be testing e-reader experience on my rm2.
If you browse around Go's stdlib use of sync.Pool, you'll see a variety of tiered pools with fixed sizes, and many drop anything over a large enough size (sometimes gigantic! as much as 16KB!): https://cs.opensource.google/go/go/+/refs/tags/go1.24.0:src/...
It's a pretty well-established gotcha, sadly, and https://github.com/teivah/100-go-mistakes/blob/master/src/12... falls right into it.
After copy editing multiple chapters, they sent it back to me with all the content on a single line. I was so incredibly upset that they ditched all my painstaking format that I almost abandoned the project there + then.
It sounds like from your experience that it has barely changed. I ended up moving to self-publishing so I have a greater control over the whole process. I wrote it up long-form here: https://ryanbigg.com/2015/08/my-self-publishing-success-stor...
Someone likely loaded that into some tool, made changes and saved and likely never even looked at the XML.
Why would anyone care what the XML looks like?
Might as well write it in Word if that's the case.
A little secret about the book is a lot of the "mistakes" are introductions to some aspect of Go worded as a mistake. "Not using fuzzing" and "Not using errgroup" are a couple of examples.
Now that I'm starting another big Go project I'm going to look at it again.
What I like most about this book is it feels like it's all "real world" stuff. You can tell the author has built a lot with Go and can save you time by telling you were the potholes are. Great stuff!
That was the funny part from the intro of the article - the author had not, in fact, build a lot with Go at the time.
But, it proves you don't actually need to in order to become knowledgeable about a subject and / or write a book.
So many programming books are like that, and usually it shows.
Is there a reason the common mistake is about goroutines specifically? If I instead just made function closures without launching off goroutines, would they all refer to the same 'i' variable? (I assume it's maybe just that the mistake tends to go hand in hand with goroutine-launching code in a pattern like that).
I'd presume the book would say right after the example :)
But otherwise: the author gets serious respect from me for going through that process, taking feedback and learning how to communicate, i.e. taking "how do I make a good book?" very seriously and trying their best. And also things like for putting their foot down when the problematic copyeditor. I'm almost interested in the book, not for learning about Go but learning about what it looks like when I know the writing has some serious intent behind it to communicate clearly.
Thank you very much for your comment, though. It means a lot.
You give me a feeling you really care about the craft and just making a good useful resource, which what I respect. I looked around the site and bookmarked it as a technical writing example I might go to read around now and then.
I sometimes teach coding or general computing things (but hands-on, less about writing) and I've come to appreciate that sometimes it is extraordinarily difficult to educate on or communicate complicated ideas.
Quoting you: To give you a sense of what I mean by improving the book “over and over“, keep in mind that between feedback from my DE, external reviewers, and others, there are parts of the book that I rewrote more than ten times.
I also do rewriting especially with content I intend to be a resource or education piece. Obsessively rewrite. Make it shorter. Clearer. Oops that reads like crap let's start over. IMO having an urge to do this and address all feedback or your own itches means you care about your work. Just have to remind myself that that perfect is the enemy of good enough (or something like that I forgot if the expression went exactly like that).
"We might expect this code to print 123 in no particular order" should really say "exactly" or "in order", since it's proved in the next paragraph to be inconsistent.
And that would be the layman's explanation of concurrency resulting in things added sequentially happening out of order.
And assuming FIFO on async execution, akin to running everything in series, is probably the first mistake anyone will make when they encounter concurrency for the first time.
1) In Go, the 'i' variable in the for loop is the same 'i' for each round of the iteration, meaning closures created inside the loop all refer to that same 'i' variable, instead of getting their own copy of it. Very easy to accidentally think the all closures have their own copy of 'i'. Goroutines are only mentioned because in Golang this mistake tends to come up with Goroutines because of a common code pattern.
OR
2) Goroutines themselves either behave or have some weird lexical scope rules in a way I don't know and it doesn't really have to do with closures but an entirely Golang-foreign-alien concept to me I cannot see, and this is why the book example had Goroutines mentioned with the mistake.
I rarely write Go myself so I was curious :) It looks like it was 1) unless I am bad at reading, and I think the Go 1.22 change is good. I could easily imagine myself and others making that mistake even with the knowledge to be careful around this sort of code (the link shows a more complicated example when scrolling down that IMO is a good motivating example).
You think you're working with a value but you're actually working with a reference to a value under the hood.
Such a nice place to work, where you can just decide "Let's implement thing A in a completely new stack for us that shows promise" and then, after some time, say, "Ah... this is too hard, bad decision though. Let's try another one"
I have a hard time with this point. It feels to me like a lot of books have A LOT of unecassery padding all over the place.
The example of taking 28 words and turning it to 120 is pretty good at showing this. The first paragraph is totally pointless - we are reading a book about 100 most common mistakes, obviously this mistake is very common, how did this increased the value?
Then we have another line that explaining what happens in the code, which is totally useless because the code is super trivial.
Then the code, with more explanations on the side as if the previous line was not clear.
And only after that we get to the crux of the issue.
I understand that book publishers feel they need to justify the price of a book by reaching the 300p mark in some or other way, but in my way this only makes the book worse.
> The first paragraph is totally pointless - we are reading a book about 100 most common mistakes, obviously this mistake is very common, how did this increased the value?
There are different levels in terms of common mistakes, and this one was probably one that all the devs did at some point. So I think highlighting the fact it's a frequent one does make sense.
> Then we have another line that explaining what happens in the code, which is totally useless because the code is super trivial.
I have a rule: always explain the intention of the code. Even if it's 5 lines of code, it helps the reader to better understand what we will want to highlight.
> Then the code, with more explanations on the side as if the previous line was not clear.
The explanations on the side do not impact the size of the book so the argument doesn't hold. I did it in many code snippets to highlight where the reader needs to focus.
> I understand that book publishers feel they need to justify the price of a book by reaching the 300p mark in some or other way
This is more about guiding the readers, making sure the expectations are crystal clear and that they can follow me throughout an explanation. You judge it as a criteria to justify the price of the book, but it's not the real reason. At least not for my book and I'm sure it's the case for many others :)
Sure, but this holds true for the blog version as well, right?
To be clear, I'm not advocating for The Little Schemer version, and am not arguing that the blog version is the best it can be, but surely we can agree that book padding phenomenon does exist.
By the way, I have read parts of your book over at O'Reilly Learning, and I do think it is a good book. So I'm not trying to take a dump on your work. My criticism is aimed at publishers.
Instead, my DE multiple times told me that it's better to favor just-in-time teaching over just-in-case teaching. Meaning multiple times, he made me drop certain section because they weren't really serving the chapter. They were "perhaps helpful" and he made me drop all of those.
I guess it also depends on who you're working with and which publisher. On this aspect, Manning was fair, imo.
I've worked with editorial teams and I'd rather have that than PDFs and/or Word files without version control.
On a different note, def. feel you pain regarding the copyeditor.
I usually avoid them by not using go. Or waiting until missing features (generics) are added.
And languages with no room for mistakes have their own issues, like readability or productivity, but I don't have any experience with those; what language(s) are you thinking of? I don't know it myself but Rust seems more "bolted down" when it comes to that aspect.
There is no honesty in praising yourself, no matter what you did and achieved.
Honesty is when you pay tribute to someone else by saying he is a source of inspiration.