MSDN Annotations - bringing it client-side

  • Article

Public annotations can be useful, but sometimes the audience of 'everyone' can simply be too broad. Consider some examples:

  • I read the blog of a developer who has a really specific focus on a particular topic. His/her chatter really interests me, but is possibly noise to the vast majority. Many blogger can expose their commentary as feeds and I can pick and choose just those that interest me.
  • I work with a team of developers on a corporate intranet. We ve got some comments to add to the documentation, but some of the content contains confidential information. We want everyone on the team to have access but no-one else.
  • I'm an individual who always likes to add a few notes to MSDN docs. I have a habit of printing a page, handwriting my notes on it and promptly losing it. My paper filing system is not as effective as I would like.

All of these scenarios are possible today. Here's how it works:

As an annotation provider...

We'll use this blog post as an example. Suppose I have something interesting to say about the home page of the Longhorn SDK documentation (which lives here https://longhorn.msdn.microsoft.com/lhsdk/port_lhsdk_home.aspx). As the feed author, simply including the URL to the home page in the previous sentence was enough for this entry to become an annotation.

More formally, as an annotation provider I need to create an RSS/2.0 compliant XML feed. Any <entry> items that should be considered annotation candidates should contain an anchor tag with the href pointing to somewhere under longhorn.msdn.microsoft.com within the <description> element. Most blog software can be used out of the box for this purpose just include a hyperlink to the relevant content in your post.

As a reader...

Just three steps (and the first is once-only):

  1. Install the client-side component
  2. Modify my Subscriptions preferences.
    1. Click the Subscriptions link
    2. Enter the feed URL (my blog's feed is https://blogs.msdn.com/aoakley/Rss.aspx )
    3. Save preferences
  3. Visit the Longhorn SDK home page to see my annotation.

Behind the scenes, the component is working through the list of feeds in the subscription list. On a daily cycle, it requests the RSS feed, parses it for any annotation candidates and caches those locally. When visiting a page, it searches this cache for any matches (based on URL) and if any are found, they'll show up automatically.