Challenges Developers Face while Developing with Microsoft, or, How Microsoft expects Developers to learn.
After publishing a recent post, I got some feedback from developers that I have seen a number of times. “What is up with the scarce documentation that always shows up when I end up on MSDN?” This is the common plight of the Microsoft developer – they have just started developing or are in the middle of a project, they search for an API expecting comprehensive guidance, and they get a page that looks like it was a placeholder.
The problem for developers, summarized
Microsoft docs are scarce, and rarely cover end-to-end scenarios. Search results typically turn up reference pages that from time to time aren’t very awesome.A good example of this (that I wrote, rushing to meet DOJ requirements) can be seen here: IContactProperties::DeleteLabels Method. This is an example of a topic that covers the bare minimum, “F” level quality.
The problem for writers, summarized
Programming writers typically are responsible for as much content as they can take on… with a little more added on for good measure. For example, while I was writing, I was responsible for around 2000-4000 topics that were either authored, inherited, or generated. These map 1:1 to public APIs that ship in SDKs and must meet certain minimum standards for every topic. This means that many APIs, despite rarely being used by developers, must be documented. As such, writers try to identify the important APIs and dedicate more time to them while focusing their best efforts on the most used APIs.
The source of the problem
As a symptom of every API being documented, many of the placeholder pages have precedence in search because the title and heading are exact matches for a search term. This can yield landing pages and entry points for developers into the “bad” docs. As such, it seems like much of the stuff that should be documented isn’t sufficiently documented at all and this situation creates the problem for developers.
For programmer writers, the breadth of content that must be covered makes it difficult to address everything as well as they would like. A lot of the time, writer’s work gets churned with API changes and the 200-300 APIs that a writer documented for a release with meticulous care were changed so that the documentation is out of sync or out of date and must be redone on a very tight schedule.
The “solution”
To address these issues, Microsoft has come up with a number of solutions over the years. The first is to use carefully structured documentation. Developer documentation typically is authored within the latest content template that standards bodies across Microsoft try to adhere to. When I was a writer, the content was organized as follows:
• About
• Programming Guide
• Reference
We go another step and specify how the content should be authored so that things appear consistently from topic to topic. The template when I was a writer was something similar to:
• Syntax
• Parameters
• Return Value
• Remarks
• Examples
• See Also
By carefully organizing our content and structuring the documentation we create a few opportunities for throwing a bone to developers when they are learning a new SDK, API, or scenario. For example, a developer could link to a sample or programming guide topic for an API if there isn’t an example on the actual reference page. We also try to get “coverage” for topics prioritized around how much we expect developers to use a topic. We also have sophisticated tools for sharing content (and code!) across topics and for validating that our code builds and works.
Taking the time to organize our content and publish it as we do is great and all, but we still don’t educate developers on our content structure so developers still don’t know how to find the content they need to get to – almost inevitable with their own deadlines looming and things not working as they expect.
How Microsoft expects developers to use the documentation
So, now on to the point of my post. The following is how Microsoft expects developers to use the documentation given the structure of our content and how we learn internally:
1) Read the About content to learn the architecture of an API
2) Determine your scenarios and find them in the Programming Guide or download a sample from/with the SDK and get started with that
3) If developers encounter challenges or need details of an API, they can click the reference to get deeper information about a specific API
My best example from content that I have authored is this:
1) Learn about Windows Touch, Architectural Overview
2) Choose the right approach to touch for you
3) Code something simple as demonstrated in “Detecting and Tracking Multiple Touch Points”
At this point I expected the developer (reader) to have a basic understanding of what Windows Touch is and how it works in code. The developer should have a project that works and does something (draw different colored touch points on their screen) and should be thinking about how they can use this in a larger context.
The reality is that this story isn’t as complete as we would like it to be. Writers aren’t forced to author in a specific structure and documentation can vary from team to team.
Additional solutions from MSDN and Microsoft
Structuring our content as we do hasn't worked as well as we expected. So, we also have developer centers such as the Windows Desktop Developer Center which pretty much function as a band-aid for the missing or confusing structure that exist within MSDN. Centers work pretty much as indexes and alternative tables of content to the large ones that exist within the MSDN library. I'm currently working to make sure that for Windows, we get better with this and I'm constantly hard at work on improving the content and organization and enabling writers to improve their content and reveal the best topics using the developer center. I'm also working on documenting "how to learn with MSDN" and this article is a brief dump of some of my brainstorming. The following notes will later be lengthened and surfaced through the center.
Some pro tips for learning
Find the “Programming Guide” . This content does not exist for every documented API group, but if you can find, it the programming guide should be a goldmine of information for you.
Avoid reference topics if you are getting started. This is referred to as RTFM (read the fun manual) in certain circles… But it’s true. If you jump in with just the APIs, which oftentimes are rushed to be published, it can be difficult to understand what’s going on and rookie mistakes and gotchas are easy to encounter. Make sure to keep an eye out for Note and dig into the remarks section of APIs for gotchas. We (programmer writers) try to make it easy to avoid making the same mistakes that we made while learning how to develop the samples that we code and ship.
In reference topics, Check the See Also section for links to more useful content, especially if the topic seems particularly bare. This is an opportunity sometimes overlooked by writers, but with a reasonable frequency writers will link to the guidance topics and howto topics from the See Also section of the documentation. This content is at the bottom of virtually every page, so don’t forget to scroll down and check it out.
Finally, when you find errors, Submit Feedback to Microsoft about the documentation bug so we fix it .
Thanks for reading, send me some comments or horror stories, I love to bring the feedback to our teams because we can oftentimes get wrapped up in the way we expect customers to work when in reality they work so differently from what we expect. If my thinking on how developers learn is a little too far out there, let me know too so I can adjust to how you guys really learn!
See Also