The Seen Benefit of Open Source Documentation
Previously I posted about the fact that Microsoft has taken their documentation to the next level by moving them to GitHub – you can read about that over here –http://derekschauland.com/2018/03/12/microsoft-documentation-like-never-before-editable/.
Prior to that post, I was in Redmond and got a chance to meet some of the members of the team behind http://docs.microsoft.com, color me impressed. Not only did they walk through the process of how these docs get built, and help those of us who do not code get a handle on GitHub (thanks for that!), they were quick to act on issues, pull requests, and questions of all sorts.
During one session, there was discussion of the filter box on https://docs.microsoft.com and the fact that it simply said Filter.The trouble is that people, myself included, were searching for content there and often coming up with no results at all. Not good. This resorted to complaints about search not working and documentation being hard to find.
The trouble is that this box was just to filter the table of contents for the given set of documents by title – if the title was not matched, the results were zero. The feature was working as it was designed. The problem was that the feature was labeled poorly. Since this impacted all of https://docs.microsoft.com, I went searching for the option to provide feedback for the website itself as soon as this was raised during a session.
The change was still submitted as an issue on GitHub –https://github.com/microsoftdocs and was assigned a PM to look into it. Having been in the Microsoft space for many years, I was not sure how far this would go, or how fast it would move, if it moved at all. An assigned person to work on this issue was huge – people at Microsoft saw this issue and placed someone (thanks @ShevaDas – https://github.com/ShevaDas). Definitely a different approach from Microsoft, and a welcome one at that.
Fast forward about two weeks.There had been some back and forth between myself and the team at Microsoft around the issue, mostly for clarification, then all of a sudden an email from the issue landed in my inbox. The issue had been fixed and the TOC search box on https://docs.microsoft.com was updated to be more clear – Filter by title.
I realize that those who have used GitHub to manage software projects are used to this kind of thing, but we IT Professionals who use software written by others, and do not really think [email protected] is likely to get to anyone unless you know someone over there, certainly are not. It is nice that the feedback system for the documentation has a closed loop style to it allowing not only edits to be made, and issues to be raise directly into the backlog, but visibility into the work being done. This is huge!!
It is definitely not Ballmer’s Microsoft anymore – and I for one am excited to see just where these changes take all of us going forward.