LinkedIn | FaceBook | Twitter
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)
One of the Technical Writers in the SQL Product Group, Buck Woody, has started a blog about SQL documentation.
Here are a few interesting blog posts. Eric White's Functional Programming Tutorial is a few months old
Regarding feedback... SQL Server's documentation team highly values user feedback. The feedback mechanism that is provided with SQL Server Books Online is extremely helpful to us as we continue to make improvements to our documentation. Every piece of feedback we receive is assigned to the appropriate writer, and every piece of feedback is reviewed. Rest assured that when you provide feedback, we see it--and we try to act on it.
Feedback can be provided in two ways: by rating the content on a numeric scale, and by adding comments. The best thing for the SQL Server UE team is when we receive both a rating and a well-crafted comment that addresses the specific issue or issues. If we know, for example, that a user finds a particular topic adequate, and we also know that the user would rate the content higher if more information about a given subject within the topic were included, we can act on that. We can also act on highly positive comments, such as "This topic has exactly the right examples and just the right amount of information." This kind of comment lets us know what we are doing right, so we can continue doing it. We can also act on comments such as "This topic was confusing. I couldn't tell if I really needed to install Component X, or if that is an option. It would help if I had this information for my <job function | specific database needs | etc.>." This tells us that we need to revisit how the topic was written and make the appropriate changes for the next refresh.
The upshot: the documentation team is here to assist our customers. Customers can best help us to do that well by giving us concrete, actionable information in their comments. And we're very glad to work with our customers based on their feedback to provide the best documentation possible.
I was forwarded this post the other day about the processes that Microsoft (SQL Server in particular)
You may have noticed that the SQL Server Books Online documentation just keeps getting better and better.
Indeed BOL is getting better by the day. Has anyone ever thought of providing samples and concepts via wiki format? Ideally the reference would stay as it is.
As I mentioned in my last blog post , SQL Server is updated several times a year - our team calls this
Seeing the new blog from the doc team inspired me to ping the extended SQL team to see what active blogs
I have since visited your personal website and was quite impressed by your experience and background. Perhaps, you can provide some feedback on an idea related to documentation and training.
The idea is to try to navigate the reader through the available materials using short quizzes. For example, the system will first try to find out what the reader wants to know (such as improve performance of SQL Server 2005 on certain queries). The system would then try to find out what the user already knows (such as how to do partitioning, build primary/secondary indexes, etc). This can be done by giving the user a few multiple-choice questions related to the topics the user supposedely knows. If the user correctly answers most of the questions, the user is assumed to know those topics.
Once the system “knows” what the user knows and what the user wants to know, the system gives the user a sequence of reading materials (a.k.a. “customized book”) that will direct the user towards the objective. To measure whether the user has learned a specific topic, the system presents the user a few multiple-choice questions. In this way, there is on-going interaction between the user and the system. In my view, interactivity is one of the keys to successful learning. Personalization is another such key. So, personalized and iteractive BOL’s can be a great learning experience.
I was thinking that multiple-choice questions can themselves be stored in SQL Server database and that with due interface, people would be able not only to augment the BOL system with materials to read but also with questions to answer.
Kevin posts a link on how to help make BOL even better.
Extensive (Useful) list of blogs by SQL Server Development Team.
General SQL Server Samples team - code samples, mainly for SQL Server 2005 ISV team UE team Compact Edition
Extensive list of Blogs from SQL Server Development Team (!) General SQL Server Samples team - code samples,
Hi Buck one thing I *really* miss from the old days right up to SQL 2000 was the ability in BOL to type the work "function" or even "stored procedures" and scroll down and see a complete list of all items within the index. Since SQL 2005, this is not possible. Not so much a problem for most stored procedures (since you can type sp_ for list) but for function names you have no such commonality. Please please can all similiar object types be grouped as children under their classification?
Keep up the good work,
SQL is really beneficial to deal with the total query language system so its very important,thanks .