6 things I dislike about MSDN
1. No date of publication/update - I often land up in MSDN via search engines. There have been countless times when I've read half-way through a piece of documentation and then found the article to be obsolete or referring to an older version. In recent years, MSDN does have a drop-down to switch between versions of the product documentation but this is not consistent across its range of products. Does it hurt to have a date of publication/update?
2. Lacks images & illustrations - Realizing the importance of illustrations in quality content, Philip Greenspun, a teacher at MIT, donated $20,000 specifically to fund the creation and improvement of illustrations for Wikimedia. He wrote, “It occurred to me that when the dust settled on the Wikipedia versus Britannica question, the likely conclusion would be ‘Wikipedia is more up to date; Britannica has better illustrations.’”.
There are numerous places in MSDN, where I wished there were illustrations to go with the explanation. It is as if an MSDN article template doesn't allow images.
3. Not well-archived - SharePoint 2010 can be made to run on Windows Vista & Windows 7. MSDN used to have a detailed step by step article that I had bookmarked. When I wanted to forward that to a friend, I noticed that the content of the page had got replaced. I couldn't believe MSDN could remove it just like that instead of archiving it! Thankfully The Wayback Machine has a copy of Setting Up the Development Environment for SharePoint 2010 on Windows Vista, Windows 7, and Windows Server 2008. There is no assurance that some nugget of MSDN info that you bookmarked will not lead you to a broken URL.
4. Inconsistent style - Microsoft publishes documentation on a whole range of products. When you switch from say, Azure to C# documentation, I would like the flow, organization and style of presentation to be similar. Instead, some sections have links that redirect you annoyingly to other sets of hyperlinks.
5. Hardly memorable URLs - Wikipedia has over 3 million articles in English (2011 estimate). With a little effort you can guess the URL for a topic once you understand the pattern by which Wikipedia builds URLs. Try doing that for a MSDN article.
6. Can't view output of code samples - The MSDN documentation on Bing Maps has some excellent code samples. However, you will have to copy the code and build your own sample to see it in action. For web-based samples, can't MSDN host those samples online so that readers can also try them out immediately. W3Schools has been letting readers run samples on their site since a very long time.
2. Lacks images & illustrations - Realizing the importance of illustrations in quality content, Philip Greenspun, a teacher at MIT, donated $20,000 specifically to fund the creation and improvement of illustrations for Wikimedia. He wrote, “It occurred to me that when the dust settled on the Wikipedia versus Britannica question, the likely conclusion would be ‘Wikipedia is more up to date; Britannica has better illustrations.’”.
There are numerous places in MSDN, where I wished there were illustrations to go with the explanation. It is as if an MSDN article template doesn't allow images.
3. Not well-archived - SharePoint 2010 can be made to run on Windows Vista & Windows 7. MSDN used to have a detailed step by step article that I had bookmarked. When I wanted to forward that to a friend, I noticed that the content of the page had got replaced. I couldn't believe MSDN could remove it just like that instead of archiving it! Thankfully The Wayback Machine has a copy of Setting Up the Development Environment for SharePoint 2010 on Windows Vista, Windows 7, and Windows Server 2008. There is no assurance that some nugget of MSDN info that you bookmarked will not lead you to a broken URL.
4. Inconsistent style - Microsoft publishes documentation on a whole range of products. When you switch from say, Azure to C# documentation, I would like the flow, organization and style of presentation to be similar. Instead, some sections have links that redirect you annoyingly to other sets of hyperlinks.
5. Hardly memorable URLs - Wikipedia has over 3 million articles in English (2011 estimate). With a little effort you can guess the URL for a topic once you understand the pattern by which Wikipedia builds URLs. Try doing that for a MSDN article.
6. Can't view output of code samples - The MSDN documentation on Bing Maps has some excellent code samples. However, you will have to copy the code and build your own sample to see it in action. For web-based samples, can't MSDN host those samples online so that readers can also try them out immediately. W3Schools has been letting readers run samples on their site since a very long time.
Comments
Post a Comment