Microsoft continues to embrace open source and community driven content. The latest evolution comes in the form of Microsoft PowerShell help reference. PowerShell help is the reference content that shows up in the product when the Get-Help command is run on a cmdlet. The content is also displayed on docs.microsoft.com.
Previously, Microsoft PowerShell help for Office content was in a proprietary system deep inside an undisclosed location known only to the top echelons of decision makers and content developers. Microsoft decided to open source this content using Git and GitHub. Making a transition from a proprietary system to an open source system is never easy.
To take on this transition Microsoft utilized an open source tool called PlatyPS, https://github.com/PowerShell/platyPS, and a public Git repository on GitHub, https://github.com/microsoftdocs/office-docs-powershell — short URL aka.ms/office-powershell.
The Project
PlatyPS is an open source tool that provides content transitions such as creating new Markdown formatted files from PowerShell modules. Microsoft used the tool to jump start the open source reference content on GitHub. Microsoft started by creating a one-way transition from the Office modules into Markdown content.
Next, PlatyPS was used again as a set of workflows to consolidate and merge the multiple product versions. The result was a streamlined set of content with a single reference file, across all product versions, per cmdlet name.
With this done PlatyPS continues to be used to update content and generate the packages that the Update-Help system uses to update help within the Office products. Microsoft chose PlatyPS because it provides a simple, commonly acceptable and understandable markdown markup language that is easily updated by the broader community yet continues to work with the PowerShell help and update system.
The PlatyPS tool is incredibly powerful and was a perfect fit for the open source efforts of Microsoft PowerShell.
Project Details
We started with nearly 60,000 Office cmdlet reference articles on TechNet. We used PlatyPS to merge these down to just over 7,000 distinct references, resulting in a single reference per unique cmdlet. This was achieved by leveraging the new Merge-MarkdownHelp feature in PlatyPS.
The Merging of multiple articles into a single article has several benefits. One of the biggest is that it shines a spotlight on the content and forces an action to address issues and ‘clean up’ content. This results in much cleaner help content and customers win. It also results in better search experience because you will only see one result per cmdlet as opposed to 4 or 5 nearly identical topics.
The products included:
- SharePoint Server 2010
- SharePoint Server 2013
- SharePoint Server 2016
- Project Server 2010
- Project Server 2013
- Project Server 2016
- SharePoint Online
- Lync Server 2010
- Lync Server 2013
- Skype for Business Server 2015
- Skype for Business Online
- Microsoft Teams
- Exchange Server 2010
- Exchange Server 2013
- Exchange Server 2016
- Exchange Online
- Office Online Server
- Office 365
- StaffHub
In addition, Microsoft is working with the community as the 2019 wave of Office is released. The content for 2019 is being developed on GitHub with the help of all interested parties. This will ensure the content will be reviewed by all interested community members before being used in production.
Benefits of Open Source to Office
Open source content has a number of benefits to Office and the Office community. In particular, the community can take ownership of the content and help each other by sharing tips and tricks that appear right in the source content. The content also moves away from a 'ship it' mentality and is constantly improving in a harmonious cycle. As issues are found the results go back into the content and the product to provide constant improvements. This removes the bottleneck for feedback loops and opens the door for content and product innovation with direct customer and community participation.
An open model also allows content to be easily extended. For example, a big request has been downloadable offline content. This is possible now since all content is in markdown on GitHub. An iPhone or Android app or Windows Store app can be developed to pull the content and work in an offline first mode. The possibilities are really only limited by the desire of the community and effort to make something happen.
The end result is that the community, such as MVP’s and highly engaged customers, can take ownership and drive the best content for everybody.
Conclusion
Using an open source project to kick-start a new open source project shows the power of the strategy. Since the inception of the open source PowerShell for Office project in late 2017 the reference content has already dramatically increased in contributions and quality. As of mid 2018 there are well over 2,000 commits by over 60 unique contributors and the numbers are growing daily. The power of the community is already proving key to the next evolution of Microsoft’s content strategy.