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.

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.

A quick note about something I learned. When talking to the Docs team, I learned a few things about links and Alt text on the Internet – these items are helpful for people using a screen reader. To make this more useful, keeping the URL spelled out in posts and documents allows the reader to go through the link rather than just seeing – Click Here. It is far more useful to spell out a website than rely on the poster to know that Click Here goes somewhere useful. As for Alt Text – screen readers cannot read images – using descriptive Alt-text helps the screen reader explain the image to the site visitor – this is infact the intention of a screen reader. Be descriptive in your Alt text and links on your site. Maybe it will increase your readership by one, two, or two hundered – maybe it won’t, but your content will be better for it.
Written on March 24, 2018