In a brief Twitter conversation with Wendy Pastrick (blog | Twitter), who is also another great SQL person out there (just incase you didn’t know), she had this to say:
“I do wish whitepapers were more interesting of a read at times. I’ve fallen asleep on a few.”
I couldn’t agree more, and let me expound on that. (Hey, it’s my blog so I could do it anyway!)

If you don’t know, I’ve written quite a bit over the years (check out some of the links on the main SQLHA.com site which has some of them) including the books I’ve authored or co-authored. I’m always doing some kind of content, and doubt I’ll ever stop. However, when I’ve done some writing for clients, every now and then I’ll get the comments back that the writing style is not formal enough or that I use some colloquial phrases which won’t fly (oops! there’s one …). While I see their point, and in some cases they are probably right, I’ll go back to Wendy’s quote. Most people would rather it be a bit less formal and easy to read than stiff as a board. There is a happy medium somewhere that blends readability with great technical content. They do not need to be mutually exclusive.

I’m not saying more formal writing does not have its place nor were my reviewers wrong. In some cases over the years, reviewers were absolutely, 100% correct. Sometimes things can be a little too informal … and that’s why I have reviewers actually look at not only accuracy of content, but readability. Both are very important not only to me, but you, the reader. If you have content that is well written but sucks in terms of its technical accuracy, why even bother? Same for the reverse: if it is technically right but hard to read and ultimately misses its audience, it’s a waste of time for everyone involved.

I do want to say one thing about reviewers. I always read every comment they write – good or bad. Good ones will call me out on everything, even down to a missing period or a misspelling. If I blundered something technical, absolutely flog me. I have no ego about it. Did I completely miss something I should have talked about? Let me know. Sometimes it’s possible to add, in other cases, no for various reasons that could be their own blog post (ah, politics!).

With lots of reviews come lots of opinions. I often get polar opposites (loved it/hated it). At the end of the day, I need to figure out which one to go with and stick to my decision. I try to take consensus. If there is a lone dissenter, they’re often an outlayer (outside of being technically wrong). If it’s a lot of folks, genuine issue. If it’s some but not all, I need to think about it a bit more. One of the advantages of having multiple reviewers is that it’s invaluable, but it’s also a bit of a curse because it does add a lot of work for an author.

Back to the topic at hand. If doing a whitepaper or training course for someone like Microsoft or another company (which may or may not have my name attached to it), chances are it needs to be a bit more formal. Using colloquial phrases can be problematic even in informal writing because they are not always universal around the world. For example, saying something like, “Boy, implemeting things like this is like taking a swing for the fences and striking out.” While you can get the meaning from the context, it’s a baseball reference. Baseball is far from a universally known sport, let alone its idiosyncrasies and nuances. Over the years I’ve become much better at recognizing that and most of it gets excised before final drafts, but it does not always happen. So I apologize in advance if you do not always get some of that stuff in a publication that has me associated with it.

Having said that, I do rely on editors in this entire process. While I try to catch a lot of this kind of stuff, it’s really up to them to a large degree to try to fix any wording or verbiage that is not up to snuff, or mark it so I can deal with it. Good editors excel at this and bad ones miss it entirely. Every client may even have a “house style” as to how they prefer something to sound/read, and I’m fine with that – they just need to let me know.

Bottom line: realize before you get something to read, it’s been through a lot of people’s hands. One thing with editors that I’ve found is that if they are unfamiliar with SQL Server, sometimes they’ll alter wording in a way that is wrong so I’ll have to work with them to come up with something that works for both of us. Trust me, there’s a lot of work that goes into writing a document that no one ever sees. If it was easier, I think more people would do it (if they like to write, that is; most people hate to compose documentation of any sort).

I’ve had quite a few people over the years after reading some of my stuff (especially my 2005 and 2008 books) that they can hear “my voice” in them. That’s great, because I tend to think that people who know me or have possibly seen me speak can see that. One of the hardest things to do is take concepts that could be difficult or complex, and make them either relatable or easy to understand. For me, it’s not unlike writing a fiction story. What do I mean by that?

Whenever I sit down to write something, especially a whitepaper or book, I try to figure out who my audience is and what story I want to tell. You need to start out at A and end up at Z. The thoughts need to be coherent and build on one another. For example, I’ve always maintained you can’t really talk about SQL Server failover clustering without understanding and explaining the Windows side of things. It’s why I put it in my books and cover it before I talk about the SQL part. However, when I explain the Windows side, I do it from a SQL perspective and address it that way so it ties everything together. So even though Windows is a bit of a left turn, it’s all part of the same thing. It’s up to me as the author, to tie it all together and wrap it up into a neat bow.

A big thanks to Wendy for inspiring this blog post, and all of this is quite relevant as I embark on the planning process for the Denali followup to the 2000, 2005, and 2008 books. By the time you see that book, the content will have been vetted technically by reviewers, massaged and altered (probably a few times), and had its makeup applied so it looks pretty for you. I’ll make a more formal announcement of my plans for the Denali book soon … it’s shaping up nicely.