SQL Server Books Online
Most of us have stacks of books on our shelves about SQL Server. But you also have an amazing resource that you get for free with SQL Server, or even on the web: Books Online. Some of you might not know how SQL Server Books Online is put together and what goes into it, so I thought I’d explain what’s going on in that part of Microsoft. I'm only talking generally about Books Online here - there are dozens of other teams dedicated to producing and releasing all kinds of documentation and information here at Microsoft, including marketing, legal and many technical teams. Although I'll mention some of the core teams invloved in Books Online, there are many others that are involved in the process. And this kind of work goes on for the server and application teams as well as games and hardware that Microsoft produces. Keep in mind that this is information I've created from my vantage point, which certainly isn't all-inclusive!
Books Online (BOL) has over 58,000 pages of content. That’s a lot of reference, conceptual and example information. It uses two interfaces: one on the web (http://msdn2.microsoft.com/en-us/library/ms130214.aspx) and a local client, which is shared with Visual Studio. In fact, you can use this local help client inside Visual Studio or in SQL Server Management Studio, which I’ll blog about some other time. BOL is distributed in over 7 languages, is subject to legal and cultural restrictions, and is accessible to those with disabilities, including the blind. That means that every word has to be legally responsible, translatable and able to be read by a machine. That includes the graphics, which means that there is a lot of text behind a graphic that you never “see”. Even screenshots have to be legal, translatable and so on.
There are dozens of writers that work on Books Online, and they do it differently than the technical writing done in some shops. In other places I’ve worked, the product team develops a new piece of software and when that process is largely complete, the technical writer gathers as much information as possible and writes the documentation. They often use a tool that not only allows them to author, but they also create their distribution (whether on the web or in a help file) at the same time. If it’s a big shop they might also have an editor that reviews the content. The content is most often checked for accuracy by a senior developer.
Microsoft works this a little differently. Many of the technical writers here are database professionals before coming to work here, and some have authored a few commercial books on SQL Server. They not only have to know the technical side of the product, but also be able to write. In effect they have two careers.
The writers get involved when the development team gets new work to do.They sit with the team during design, testing and deployment. The writers author the content as the code is written, delivering their documentation at the same time as the product. This even happens during Community Technical Previews, which is why you’ll see the documentation grow and change with each CTP. They are quite vocal about what goes into the product, and have some really passionate discussions about how things are implemented. This means that when you provide feedback through Books Online, you actually have a path to the developers.
Not only do the writers write new material, but they also change current content. Books Online (the current version) is refreshed several times a year (you are downloading that, aren’t you? http://www.microsoft.com/downloads/results.aspx?pocId=E49D77BF-D5AE-4EC6-9DFA-D7A19DBA995E&freetext=Books%20Online&DisplayLang=en), and each time you hit the “feedback” button on the web or in the local help client you open a bug against a writer. They follow these through, even if for whatever reason the topic can’t be changed.
Writers also author other material – READMEs, whitepapers, guides, error strings, the text in the Best Practices Analyzer and more. There’s a lot of info to circulate. But the writers don’t work alone. Each team of writers has at least one editor that checks everything that is written. Technical reviewers ensure that the examples work. A full team of people works on translation, and yet another team works on the distribution of the content to the web and the local client. Developers review and check the documentation on their code. Security experts comb through the material to ensure that it is as safe as possible. It’s a lot of work to produce a book that takes you from beginner to expert in a single help offering.
So are there mistakes? Of course there are. That’s why the feedback mechanism is there. Would we like to change things? You bet. And we will – but with an eye on producing the highest quality information in the industry. Sure, we’ve all been frustrated when we can’t find something or run into the odd example that doesn’t work the way we think it should. But working together, we can make it better.
(Podcast Attached, click title above to access file if you're in the default view)
