Microsoft invests substantial resources in supporting developers; yet the last two topics I have explored in earnest – the Azure blob storage service, and ASP.NET MVC with Azure Active Directory integration – have been frustrating and difficult. Admittedly I am only an occasional developer, but I suspect my experience is common. What is going wrong, and how could Microsoft improve?
Among the problems I have encountered:
- Abundant documentation of simple first steps with a vacuum for anything more advanced
- Samples that do not run without tweaking
- Samples designed for old versions of Visual Studio
- Samples which use obsolete or deprecated libraries
- Samples which are poor solutions for the problem they are supposed to address
- Documentation or samples which use preview, beta or even alpha libraries. Microsoft sometimes seems to make more effort documenting what is in preview than what is fully released.
- Posts on a topic which are out of date, but for which it is hard to find something current
- Circular links – click here for more information – you get another article which links back to the first one, perhaps with an intermediate step
- Poor quality responses to questions on official Microsoft forums
On the positive side, the reference documentation is not too bad. StackOverflow is a great resource and seems to attract higher quality responses (even sometimes from Microsoft staff) than the company’s own forums.
Here then are some of the improvements I would like to see:
1. A sharper distinction between what is in preview and what is production-ready. For any given problem, it would be great to find a clear statement of how you should address it for production now, with fully released and supported libraries, and another statement showing how you will be able to address it with the latest and greatest (but perhaps less stable) technology which is in preview.
2. For key teams in Microsoft to maintain sites which offer clearly delineated production and preview sections and which are kept rigorously up to date.
3. More short samples and fewer “this demonstrates everything” samples. Large samples are more difficult to install and study and have more complex dependencies.
4. Posts and their accompanying code inevitably go out of date and I do not favour removing them, which causes more difficulties than it solves (broken links). However it seems to me reasonable for teams to maintain a number of key samples for their product area and keep them up to date.
What am I missing – or am I complaining too much about what is normal in software development? As ever, I welcome your views.