This is the second part in the series of new things that are afoot with the MSDN websites. In this posting, I would like to discuss some changes in the posting of articles and code samples. As an example of the new experience, I’d like to draw attention to a refreshed article that was recently updated and reposted from Morgan Skinner, ’Creating a Custom WF Activity.’
In the prior years, we made extensive use of the MSDN Online Library. Information on the MSDN Online Library takes one of two forms. There is the documentation that is written by the product group, which is typically posted under the WF 3.5 documentation node and WCF 3.5 documentation node of the taxonomy tree. There is also the whitepapers that were created outside of the product group – be that folks from the field, Microsoft Consultants, or external MVPs; these typically were posted in the ’Articles and Overviews’ nodes (one for WCF Articles and Overviews, and one for WF Articles and Overviews) of the taxonomy tree.
Whitepaper Articles
Posting the whitepapers into the MSDN Online Library provided a series of benefits – including the inclusion in the installable documentation and consistency of the MTPS (MSDN & TechNet Publishing System); it also had drawbacks, primarily around flexibility, formatting, and discoverability. A major complaint that has come up about the way we’ve been doing things is that it makes it very hard to find new content that has been published into the systemwhich is a fair argument – the system has been well designed as a online version of an installed documentation library; it just wasn’t designed for the casual reader to regularly drop in and look for updates.
With the new MSDN Social Content servers, we now additional flexibility. Articles get the benefit of HTML (and are limited more by the CSS and ASP.NET template structure, rather than being limited to a handful of standard HTML tags).
Because of this, we’re trying to make articles posted to the new system a bit more interactive and easier to explore and relate to one another. To the right is a screenshot of Morgan’s article. I’ve called out a few of the new features, that I’m hoping help the reader get a better experience. There will likely be a few changes to the layout over the next couple weeks as we publish a few more articles up to the server and get a feel for what works (and what doesn’t), and based on community feedback (if you have feedback – as always – either post a comment below or use the contact link to the right to send us an e-mail).
In addition to the tagging capabilities (covered in my prior post on the new MSDN Dev Center pages), you’ll notice that we have created a grey ’About this Article’ box. I know grey isn’t all that inspiring, but we did it to be consistent with the MSDN Online Library ’This relates to version’ box, and it’s flexible – let me know if you feel strongly about it. Within this box, we try to provide a list of the related technologies, a link to related downloads and related articles, and a mini table of contents to let users jump to the section of the article they may be most interested in. Additionally, we’ve moved the ’About the Author’ up from the bottom to the right column.
Code Samples
For code samples, there really wasn’t a convenient place to put them. As a result, many of the code samples were posted up to the Microsoft.com Downloads website. Because of this limitation, the NetFX team had created the NetFX3.com website to host code samples. With the new MSDN platform, we now have two repositories for code samples and sample applications:
- CodePlex: CodePlex is Microsoft’s server for hosting open source projects. Projects hosted in the CodePlex environment can be both Microsoft sponsored, as well as community led/owned – and include a TFS backend, an integrated issue tracking database, and discussion boards for hosted projects. A few of the notable Microsoft-sponsored projects on CodePlex that stand out for me include AAA, BBB, and CCC.
- MSDN Code Gallery: The MSDN Code Gallery can be thought of as a place to post sample code and articles that involve Microsoft technologies. I believe that it is powered by the same engine as CodePlex, but isn’t intended for team-based development collaboration (Code Gallery doesn’t have the TFS backend for source control and issue tracking).
In the case of Morgan’s article, the source code has been posted up to the MSDN Code Gallery (screen shot of the Code Gallery page to the left). Posting the article via this method has many advantages over the prior method. Primary above them is the inclusion of the author in the project. In this project’s case, Morgan is co-owner of the Code Sample project, and can update the code sample as needed. As well, the author (and the MSDN Dev Center team – us) have the ability to update the project’s wiki page to point to relevant MSDN Forum posts and additional nuggets of wisdom that the community contribute to the project over its lifetime.
We’re hoping that this provides better context to those who come to the project years after it has been posted, allowing them to learn from those who came before them and hopefully not get frustrated with any issues in future service packs or DLL updates (should they occur; although we all know that code samples are perfect and never have quirks ^_^ ).
Over the coming months and years, expect to see WF and WCF projects showing up in these two repositories. We will make announcements on here and on the MSDN Dev Centers, and – as always – are interested in your opinions on what works and what doesn’t.
I hope you enjoy the new additions to the MSDN Dev Center family; happy reading – and happy coding!