We get to work with the newest and coolest software all the time. One of the biggest selling point of Office 365 is the constant stream of new features and functionality. New builds of Exchange Online are pushed into Office 365 daily, therefore new features can show up at any time.
These constant updates do come at a cost. To date, the documentation for Office 365 has not kept up with the pace of change in the service. New features and functionality are often added into Office 365 with little to no documentation. This often means that we need to figure them out on our own.
The ideal solution would be for Microsoft to invest in technical writers who can work closely with the engineering and development teams to ensure that the documentation for new features is ready when those features go live. Short of that, an acceptable secondary option is for Microsoft to democratize the documentation in a way that the IT pro community can help keep it up-to-date and accurate.
Recently Microsoft announced that all PowerShell cmdlet reference topics for Exchange Server 2010-2016, Exchange Online, Office 365 Security & Compliance Center, and Exchange Online Protection have been relocated to GitHub. In this blog post, I’m going to walk through how to use this new document library.
What is GitHub?
IT pros who primarily work with Microsoft technologies may not have had any exposure to GitHub yet, but it’s time for that to change.
GitHub web-based hosting platform mostly used for software version control. In this case, Microsoft is also using it for version control for documentation. The best place to start learning about GitHub is the Hello World document. The Hello World document walks you through the basics of using GitHub.
Where are These New Reference Topics Located?
I grew up as an IT pro with TechNet being the place to go for all things Microsoft documentation. Now it’s time to shift to a new website for Microsoft documentation.
Microsoft Docs now hosts the latest documentation for all things Exchange, Exchange Online, and Exchange Online Protection. As you can see in the screen shot below, I have signed in with my GitHub account and am able to submit feedback on the document shown.
You can use the Edit link in the upper right-hand side of the page to edit the article.
Your modifications to the article will generate a pull request (more on that below) that once approved, will update the documentation. If you notice a PowerShell cmdlet that has an attribute not in the documentation, you can go ahead and add the missing information yourself. You can even fix those annoying typos that seem to be so common in so much documentation.
Your updates will also be pushed out to other places, like the PowerShell Get-Help information for the cmdlet you updated.
There is a README file that has more information on the specifics of updating Microsoft PowerShell documentation.
Pull, Branch, and Merge: Using GitHub
If you haven’t used GitHub before, some of the terminology used can be confusing. Let’s take a minute to look at the important terms you need to know.
- Repository – A storage space within GitHub that is usually associated with a single project. Repositories can contain images, videos, spreadsheets, folders, files, and data sets.
- Branch – A version of a repository. By default, a repository has one branch called master. Branches can be used to experiment with different versions of code before committing those changes to the master branch.
- Commits – A saved change in a branch. Each commit has an associated comment used to explain what changes were made.
- Pull – A request to merger your changes into an existing branch. The process is to create your own branch of an existing project, the add your changes and create a pull request so the owner of the original branch you started working from and review and approve your changes to the project.
- Merge – A approval process that adds the changes from a pull request into your branch of a project.
It’s undeniable that this isn’t your fathers Microsoft anymore. Just a few years ago it would have been hard to imagine Microsoft embracing open source software solutions. I think a lot of the changes at Microsoft are long overdue.