Some Requests For Authors Of SQL Server Books

Heal Thyself

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.

Code Formatting

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.

Code Placement

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.

Image Quality

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.

Tech Review

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.

Concept Introduction

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.

Auto-Errata

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.

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!

Going Further

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. You can also get a quick, low cost health check with no phone time required.

Some of this will be publisher-specific but here’s my experience working with one publisher:

– Layout isn’t something I have a lot of control over. In my publisher’s case, I work from a Word template; lay out the text, images, tables, and code blocks in the proper order; and the publisher controls layout in ebook and print format. I have no idea what’s going to be on any particular page, where on the page a code listing or image will start, or how nicely it will translate to print. As an extreme example of this, I received a copy of one book which included several large images and maybe 1-3 lines of text between them. This led to a section of the book which would have, on each page, one large image and a couple lines of text. That meant several pages in a row with 30-40% blank space. The kicker is that the author probably had no idea it would turn out that way and might have re-organized things otherwise.
– I do, however, have full control over code, which means when I change styles mid-query, yeah, that’s on me… A lack of consistency in code formatting says a lot to me, namely that the author isn’t paying careful attention. That leads me as a reader to question how careful they are in everything else. That can be unfair and it doesn’t always hold true, but it’s my bias.
– Good advice on tech reviewers, though “getting a tech reviewer” seems to be a hard enough job as it is. Getting a sucker who likes you enough to do it but disagrees with you? That’s a real challenge.
– “Introduce now for a payoff later” is a valid technique, so I guess I’d say it depends more on when and how. The introduction to the book (or first chapter if there is no proper introduction) is probably going to lay out the roadmap and should give you an idea of where things are going, so I’d forgive all call-aheads in that chapter. From there, occasional call-aheads, especially in cases where you’re not prepared to go in detail on a topic yet but you expect a sharp reader to bring this up as a question or complaint here, can be fine. In those cases, I’d probably reference a call-ahead in a note rather than inline. To wrap this up by coming back into your corner, if you’re frequently doing call-aheads, that’s probably a sign that the chapter order is wrong.
– Having an Errata repo is a good idea. Some publishers, like Manning, do a pretty good job of keeping track of errata. Others aren’t as great about it, so in the latter cases, it’s really up to the author to keep track of it.

4 thoughts on “Some Requests For Authors Of SQL Server Books”

Ben Thul says:

August 8, 2022 at 11:06 am

“Auto-Errata”

You got one corner of my mouth upturned with that one. Auto-Errata notifications indeed.
Kevin Feasel says:

August 8, 2022 at 10:33 pm

Some of this will be publisher-specific but here’s my experience working with one publisher:

– Layout isn’t something I have a lot of control over. In my publisher’s case, I work from a Word template; lay out the text, images, tables, and code blocks in the proper order; and the publisher controls layout in ebook and print format. I have no idea what’s going to be on any particular page, where on the page a code listing or image will start, or how nicely it will translate to print. As an extreme example of this, I received a copy of one book which included several large images and maybe 1-3 lines of text between them. This led to a section of the book which would have, on each page, one large image and a couple lines of text. That meant several pages in a row with 30-40% blank space. The kicker is that the author probably had no idea it would turn out that way and might have re-organized things otherwise.
– I do, however, have full control over code, which means when I change styles mid-query, yeah, that’s on me… A lack of consistency in code formatting says a lot to me, namely that the author isn’t paying careful attention. That leads me as a reader to question how careful they are in everything else. That can be unfair and it doesn’t always hold true, but it’s my bias.
– Good advice on tech reviewers, though “getting a tech reviewer” seems to be a hard enough job as it is. Getting a sucker who likes you enough to do it but disagrees with you? That’s a real challenge.
– “Introduce now for a payoff later” is a valid technique, so I guess I’d say it depends more on when and how. The introduction to the book (or first chapter if there is no proper introduction) is probably going to lay out the roadmap and should give you an idea of where things are going, so I’d forgive all call-aheads in that chapter. From there, occasional call-aheads, especially in cases where you’re not prepared to go in detail on a topic yet but you expect a sharp reader to bring this up as a question or complaint here, can be fine. In those cases, I’d probably reference a call-ahead in a note rather than inline. To wrap this up by coming back into your corner, if you’re frequently doing call-aheads, that’s probably a sign that the chapter order is wrong.
– Having an Errata repo is a good idea. Some publishers, like Manning, do a pretty good job of keeping track of errata. Others aren’t as great about it, so in the latter cases, it’s really up to the author to keep track of it.
Allan Hirt says:

August 9, 2022 at 9:35 am

FWIW, your tech reviewer comment is spot on. I generally pick people who will ensure the book is right, not because they like me and will agree with me. I sometimes pick more than one and have specific people review certain parts because they are experts/do it all the time in that particular “thing”. It’s helped every book of mine in the past.

I also have general reviewers. Sometimes I will get conflicting reviews (i.e. one person says to do X, another Y for the same sectoin) and ultimately it’s my call to take one, both and cut it down the middle, or ignore.

The biggest fights I have are with editors.
Cliff Brandon says:

August 9, 2022 at 1:27 pm

Maybe a couple of additional suggestions:
1. Don’t write in the passive voice. More a problem with engineers and scientists than any other group.
Just remember, “The rabbit crosses the road”, not, “The road is crossed by the rabbit”.
2. Try to write in 15 word or less sentences (brain retention issue).
3. Try to write in only 3 sentence paragraphs.
The last two are for the Faulkner fans. I blame the cult of the twitter haiku.

Comments are closed.