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.
What you’ve missed is the popularity of the likes of GitHub. It’s continued growth has had a positive influence on software development and changed the way developers learn and understand new APIs. A comprehensive test project is the perfect complement to documentation. As software becomes increasingly complex and release cycles shorten, having an engaged community as a fallback means that open source offers such breath and efficiency it is impossible to beat. The pressures on individual organisations to compete by attempting to plan and coordinate comparable levels of support may explain your recent experiences.
ASP.NET is open source too – in fact, I downloaded the source which helped me understand it better and fix a problem in my code. Credit to Microsoft for that.
I agree, but unfortunately not all of the .NET stack is open source. The parts they have released have been to the benefit of both developers and Microsoft. If more, along with the fundamental test code, could be open sourced (including Azure components) the pain points you experienced first-hand would not be so frustrating and probably not present themselves in the first place.
A recent example of this approach is the progress of the relatively new Go programming language. Some of the packages being developed by the open source community cannot be ignored by any serious developer. The fact that both source and test code is freely available means the learning curve is not as steep as it would be otherwise and moreover, the journey upward can be an enjoyable and rewarding experience.
This aspect is often forgot but is important if we want to facilitate training and encourage more students to enter the IT industry.