Creating SDKs: Collaborations

Keep in mind that a lot of what I say below applies to the MSDN Library and may apply much less to the Longforn SDKs that I work on now. I suspect that much of this is similar - in fact I know it's pretty much the same for the Visual Studio Whidbey SDK - but different teams will often do things in different ways. Additionally, this represents my interpretation of how an SDK is managed and built, and therefore may present a distorted view of things. That said, I was part of the MSDN Quarterly Library team for nearly six years and was a part of something like 23 releases of that product. Not to mention lots and lots of releases of content to our website.

The SDK system really consists of two sets of teams: the teams that create the documentation and the teams that create collections of the documentation. In the MSDN world, the documentation creators (who we often called upstreamers) consisted of User Experience teams that worked on specific projects. For instance, the SQL Server team would create their set of documentation and then drop it to MSDN. Usually large product teams have devoted, consistent groups that acted as upstreamers. The Office team, for instance, was terrific at maintaining and managing their upstream docs, dropping them to us on a clear and consistent schedule. There are other teams, however, that create documentation as a one-shot process. They get together, create their documentation, and then move to other tasks.

Often docsets dropped to MSDN were "thrown over the wall"; that is, the upstreamers create their documentation with its own specific behaviors, style sheets, navigational schema, meta-tagging, etc. There generally isn't any policing authority to require that teams' content looks and acts the same. That's how we run into situations where different teams' glossary pages, page formatting and page behaviors look different from each other. It's always been one of the most painful aspects of the MSDN Library. Users hate it because so many pages look and act differently from each other, while production people hate it because of all the extra churn necessary to get the docs to look and act as expected in the Online Library.

Things are starting to get more uniform. You'll see more and more pages look like this, with gray headers, a drop-down language filter box and other similar formatting. Those docs are built out of DocStudio, a system that it being adopted by more and more teams throughout Microsoft. The Visual Studio team creates all their docs out of DocStudio, and in our Longhorn WinFX Library, much of the managed reference docs live in DocStudio as well. I know that some users might not like this formatting, but it at least provides the advantage of consistency throughout the SDKs. It's the role of the SDK management team to help drive compliance with company-wide standards and do everything we can do to drive uniformity. Of course, that's always hard. Teams are always stretched to the bone, overworked, and it's hard to get them to get to a place where they can take the time to invest in new tools.

You can see how this ends up being kind of a push-pull situation.

Next week I'll start to talk about some of the nuts and bolts of the process of how an SDK comes together. Please let me know if you find this sort of thing useful.