Today, developers run hither and yon around the web to get the information they need. When you look at API references, you only get a small part of the story. There are KB articles, bug info, and errata; as well as perspective and experience from the broader community that you’d like to have, but are scattered all over the internet.
I think that there’s a better way.
With annotations, we use the docs on MSDN as a way to help organize all that other useful information into a single place, so it’s easier to find what you’re looking for. Go to the API reference, and you can also see errata, insight from the community, additional samples, and the like, all in one place. The information comes from lots of difference sources, but
we can display it in a way that’ll make it easier for developers to find what they need.
So, how does it work?
Our basic idea was to add “feeds” of information to each API reference page. MS will provide an “official” feed where we’ll share late breaking information. There’s another feed where anyone can post comments and insight. Of course, comments often generate other comments, so we actually use discussion groups for this feed. And – now here’s the part that I think is most interesting – anyone can use RSS to provide a feed of their own. To consume those feeds, you just point the annotation client at the RSS feed.
These RSS feeds are the place where I think that things will get really fun. O’Reilly already has a feed up and running, and I think that other possibilities abound. A language vendor could provide a feed that served up sample code in their language. A corporation could provide an internal feed that provided their .coding guidelines. Consultants, or training companies could provide a feed that shared experience from the field. And so on.
We’ve got annotations up and running for all the documentation in the Longhorn SDK. Go check it out, and let me know what you think!