I dislike criticism without introspection, so anything that I say here I’ll also be doing my best to apply to anything I produce.
But anyway, I’m writing this because I read a lot of SQL Server books, and there are some things about them are pretty frustrating.
This goes for both print and digital copies, though some advice is specific to print copies because I think a lot of folks still buy them.
Anyway, here are some thoughts I have. You can show this post to your editors if you want. Maybe it’s their fault, not yours.
I have no idea.
While I don’t expect anyone’s coding format to be as highly-evolved to near-perfection as mine, I do prefer consistency.
Many times while reading a book, the code formatting style changes from query to query, page to page, etc.
I understand that with multiple authors, things may change between chapters (but even then, agree to something, would ya?) but it’s jarring to see queries written in several different styles throughout a book.
Most code formatting tools out there will get you at least 70% of the way to code being formatted the way you want, even if you’re particularly persnickety about things.
For the absolute love of Crispin Glover, stop putting code in places where it will span multiple pages.
It sucks for everyone, no matter how they’re reading the book, but all those nice little SQL Server Scrubs who bought (hopefully bought) the digital copy of your book have an awkward time copying and pasting things over to run locally.
For the Print-cesses of the world, we just don’t need that kind of page-turning, cliff-hanging suspense.
I’ve seen this more than anything, and it drives me bonkers every time. Just keep writing and say the code example is on the next page.
If your code example takes up a whole page and then some… Well, look, I don’t have an easy answer for you. You want it there for digital folks to copy, but no one with a print edition is going to write that all out from scratch.
Maybe you should just get yourself a nice GitHub gist and link to longer code examples? Use a URL shortener or GO codes to make memorable URLs?
Either way, this particular issue is in every book I’ve ever read.
We really need to talk about this one.
Now, I get it, you’re probably not gonna talk anyone into printing a full color SQL Server book. At least no one smart.
If you can do that, great. You’re one step closer to your book not looking like a 90’s zine about anarchy or graffiti or whatever.
The next step: use high quality images. Please, please, please, use high quality images.
No one’s going to be able to read your book and follow along without wondering if they have cataracts if they’re staring at washed-out, fuzzy images the whole way through.
Far too often, it looks like someone compressed-to-death and watered down the printer ink for every image in a book.
Get someone you disagree with to tech review your book. Not someone who’s wrong, just someone who has a different point of view.
This isn’t a pitch to get me to do it. Unless I love you to death, I’m probably not gonna wanna read and review your book.
But far too many books seem to suffer from “I got my friend to do this”, which leads to groupthink.
There’s no alternate viewpoint considered or explored, and you end up with one-sided highways of thought.
Doing a tech review shouldn’t be about toeing a line, it should be about making a book more technically accurate.
I’m not sure if this is a book or thought organization issue, but… If you’re in an early chapter of a book, say the first three, and you keep seeing things like “we cover this more in chapter 12” or 13 or 14 or some other far off place, you probably shouldn’t be doing it right then and there.
When you’re going to introduce a concept, you should either be covering it in that chapter, or covering it in the next one.
I see this quite a bit, and wonder if I need to skip way ahead in the book and read about this other thing, and then come back.
That’s a crappy, because it makes you feel lost in the material that’s supposed to be bringing you clarity on a subject.
Try to contain yourself, here. Maybe you’re saying too much too soon.
It happens to me every time I write a blog post. I re-read it as I’m going through, I re-read it when I’m done, and I tend to check in on things a day or so before it goes live.
When it goes live, I read through the post, and notice half-a-hundred things that I wanna fix, tweak, or expand on.
I can only imagine what that’s like at Bookscale© where you have 300+ pages of blog posts publishing at once.
As you make changes to the book, you should notify folks who bought it. Just randomly posting corrections is hard to keep track of.
GitHub is, again, a decent way to get and track feedback. It also gives you a way to announce large releases to the content so everyone knows when a new version is available.
Hopefully you’re making digital copies available to folks who purchase a physical copy. Otherwise, you’re gonna have a hard time getting a better product in their hands.
Reinventing The Wheel
Rather than take up a whole page with some reheated DMV query, give some love to community scripts out there that do the same thing, but better.
Anyone who knows better is going to pass right over that stuff anyway.
Thanks for reading!
If this is the kind of SQL Server stuff you love learning about, you’ll love my training. I’m offering a 75% discount to my blog readers if you click from here. I’m also available for consulting if you just don’t have time for that, and need to solve database performance problems quickly.