Share via

Challenges Developers Face while Developing with Microsoft, or, How Microsoft expects Developers to learn.

  • Article

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

Comments

  • Anonymous
    August 15, 2011
    The comment has been removed

  • Anonymous
    August 15, 2011
    @The Thanks for the feedback, please understand that we aspire to do as much as is practical see this post (http://ow.ly/63Q9N).  We have more to document than we are resourced to document and the tradeoff sometimes can be lower quality documentation. If you find specific sore spots make sure you let us know.

  • Anonymous
    August 15, 2011
    totally agree with The

  • Anonymous
    August 15, 2011
    @hach Thanks for chiming in, do you have any specific cases that we can learn from?

  • Anonymous
    August 16, 2011
    I totally disagree with The and hach. The documentation in the areas that I follow is really supurb. Look @ ADO.NET for just 1 example. Or the BB 6 printed documentation. The kicker is you just can't find it. And perhaps that's what The and hach mean. You ask how we use documentation. In my case I identify an issue that needs clarification and go looking for the answer. Most of the time it's a "How do I..." and when you search MSDN you get drivel. For kicks I searched "How do I send an email in VB6" from the MSDN Home Page and got 2,810,000 returns. None on the first page were even close to the topic. Refining the search to Knowlege Base returned only 2,050,000 hits. I recommend changing the indexing. I suggest

  • Anonymous
    August 16, 2011
    Sorry I fat-fingered writing BB6 instead of VB-6. Other documentation in the Visual Studio and SQL Server areas is also superb. BING is the worst possible tool to use on MSDN. It returns so much garbage that it becomes the engines it mocks on TV. I don't want to read about the travails of some poor user who can't send an email to Aunt Tilly. Yes, I know you can set filters but the results still aren't good. Perhaps a "How do I" metatag on articles would help.

  • Anonymous
    August 16, 2011
    The comment has been removed

  • Anonymous
    August 16, 2011
    The comment has been removed

  • Anonymous
    August 16, 2011
    I don't use only MSDN when looking out for helps, but even when I do, I get the desired response without spending so much time. I also reckon that you need to combine two or more resources to get the solution you want. You need to be able to link the various resources that point to your solution to arrive at it.

  • Anonymous
    August 16, 2011
    @msorens Thanks for the usage examples. I like your articles on smalltalk, just printed your XPATH/CSS/DOM/Selenium cheatsheets! @chinedu Good to know.  We try to use the See Also sections of pages to cross reference related APIs and larger more comprehensive programming guide materials.

  • Anonymous
    August 19, 2011
    Sure, you do the best with what you're given.  But, out of respect for your customers, maybe you can find a philanthropist who could kick in a little help?