microsoft-365-docs is the source behind the Microsoft 365 documentation

A documentation source, not a mirror of the site

The repository description is direct. It is used to host the source for the Microsoft 365 documentation on docs.microsoft.com, and the default branch is called `public`.

What that means in practice is that the Markdown files under `microsoft-365/` are the input to a publishing pipeline, and the site is the output. The README's own front matter shows the shape of a file.

---
ms.date: 9/15/2023
---

The `ms.date` field is the one piece of metadata visible here, and it is the date the article was last reviewed or updated, which is what lets a reader judge how current the guidance is. The `microsoft-365/` directory is the bulk of the tree, with a `copilot/` directory beside it, and the top level carries `CODEOWNERS`, `ContentOwners.txt`, `SECURITY.md`, `ThirdPartyNotices`, and the two licence files.

The topics attached to the repository are `core`, `lmcdocs`, `mvldocs`, `non-build` and `officedocs`, which are the documentation source sets rather than code. There is no build system to speak of, no package manifest, and no application.

The audience is primarily a reader who wants a documentation fix, and secondarily a team that wants to watch Microsoft's product guidance as a versioned corpus. The first group is what the contribution flow is designed for.

Small fixes need no software at all

The README's main contribution path is unusual and worth reading, because it removes every excuse not to fix a wrong instruction.

The framing is that contributors who make infrequent or small updates can edit the file directly on GitHub.com without installing any software. The steps are given in full.

First you verify you are signed in to GitHub.com. Then on learn.microsoft.com you find the article you want to update, and above the title of the article you select the Edit this document button, which is the same button on every article on the site. The corresponding article file opens on GitHub, where you select Edit this file, and the file opens in a line-numbered editor page where you can make your updates. There is a Preview toggle to see your changes as you go and an Edit toggle to go back.

The last three steps are the pull request. You select the green Commit changes button, which opens a Propose changes dialog with a required commit message, which you can accept as the default of `Update <filename>`, and an optional extended description that is where you explain the change or mention the GitHub alias of someone to review and merge it. Then on the Comparing changes page you select the green Create pull request button, and on the Open a pull request page you review the title and comments and select the green Create pull request button again.

The tip at the end of that section is the part with the personality. If you have no special privileges you see the steps as described, and if you have permissions to approve your own pull requests you see a similar experience with different button and page titles, for example Commit changes instead of Propose changes, extra options for creating a new branch, and fewer confirmation pages. The instruction is to click any green buttons that are presented to you until there are no more.

So the whole loop is: find the article, edit the Markdown, propose. No clone, no branch naming convention, no local preview server, and the Preview toggle on the GitHub editor page is as close to a preview as a contributor will get.

Merging is somebody else's decision

What happens after the pull request is open is described in one paragraph, and it sets the expectation properly.

The article owner, identified in metadata, is notified about the changes. Eventually the article owner or another party will review, possibly edit, and approve the changes. After the pull request is merged, the article is updated on learn.microsoft.com.

Two things follow from that. The first is that the content set is curated, and the README says the work goes into the content set after it has been reviewed and merged. The second is that a contributor's name ends up in the repository, since you are listed as a contributor in the contributors graph.

The metadata mention is worth dwelling on for a moment, because it is the mechanism that makes the model work. An article carries an owner, and that owner is the one who gets notified and who reviews. That is a much better fit for documentation than an open review queue, where a hundred unrelated corrections compete for attention, and it explains why the `CODEOWNERS` and `ContentOwners.txt` files exist at the top level of the repository.

The practical consequence for a contributor is that a correction to a specific product area is a pull request to the person or team who owns that area, and the wait depends on them rather than on a queue.

Two licences, and trademarks are not included

The legal notices section is the part of this repository most likely to matter to an organisation reusing its content, and it makes a split that is easy to miss.

Microsoft and any contributors grant you a license to the Microsoft documentation and other content in the repository under the Creative Commons Attribution 4.0 International Public License, which is the `LICENSE` file. And they grant you a license to any code in the repository under the MIT License, which is the `LICENSE-CODE` file.

So the prose is Creative Commons Attribution 4.0 and the code in the repository is MIT. That is a sensible split, since an attribution share-alike-free licence for documentation is a common choice and sample code in a docs repository is usually easy to reuse as long as the MIT notice is kept.

The second half of the notice is the part that is easy to skim and expensive to ignore. The licences for the project do not grant you rights to use any Microsoft names, logos or trademarks, and Microsoft's general trademark guidelines are linked. Microsoft, Windows, Microsoft Azure and other products referenced in the documentation may be trademarks. Microsoft and any contributors reserve all other rights, whether under copyright, patent or trademark, whether by implication, estoppel or otherwise.

In practice this means you can reuse the documentation text under CC BY 4.0, including commercially, as long as you attribute it, and you cannot publish it under a Microsoft logo or imply an endorsement. The `ThirdPartyNotices` file at the root is where the notices for third party content in the documentation live, and the `.acrolinx-config.edn` file is the configuration for the terminology checker used on the content, which tells you that the text is subject to automated checks for approved terminology before publication.

The redirection files are the interesting part of the tree

Most of the top level of the repository is a set of files with long names, and they are not incidental.

There is `.openpublishing.publish.config.json`, which is the publishing configuration, and then a long list of `.openpublishing.redirection.<area>.json` files, one per documentation area. The areas cover admin, bookings, business, campaigns, commerce, compliance, contentunderstanding, copilot, enterprise, frontline, knowledge, learning, lighthouse, loop, lti, managed-desktop, scheduler, security, services, solutions-migration, solutions, syntex, test-base, topics and viva.

These are the redirection rules for the publishing system, and they are the mechanism behind something a user of learn.microsoft.com experiences constantly. When Microsoft reorganises its documentation, the old URLs have to keep working, and the way that is done is a per-area mapping from a legacy path to a current one. Doing that with one file per product area rather than one global file means a change to the Dynamics Business area does not have to be reviewed alongside a change to Viva.

It is also a hint about the scale of the corpus. Twenty five or so areas, each with its own content set and its own URL history, is a large body of documentation with a long institutional memory. The `non-build` topic tag on the repository and the `ContentOwners.txt` file point at the same thing from the other side, which is a list of the people who own the content.

For a developer who wants to work with the docs as data, this directory is the most useful part of the tree, because it is the only place where the structure of the published site is visible as data rather than as prose.

A CLA bot and a code of conduct sit between you and the merge

Two pieces of process are worth knowing about before a first contribution.

The first is the Contributor License Agreement. The README says most contributions require you to agree to a CLA declaring that you have the right to, and actually do, grant the rights to use your contribution, and points at the Microsoft CLA site for the details. When you submit a pull request, a CLA bot automatically determines whether you need to provide a CLA and decorates the pull request appropriately, for example with a label or a comment. The instruction is that you only need to do this step once across all repos using the CLA.

That is a real friction point on the first contribution and it is worth knowing about before you write the article, because the bot's verdict arrives after the pull request is open. The one-time scope is the reassuring part, since the second contribution does not involve a second negotiation.

The second is the code of conduct. The project has adopted the Microsoft Open Source Code of Conduct, and the README points at the FAQ and gives an address, [email protected], for questions or comments about the contribution process.

Both of these are the ordinary apparatus of a large corporate open source programme, and both are visible in the repository. There is also a `SECURITY.md` at the root, which is where a security problem in the documentation, as opposed to a technical error, would be reported, and that distinction is worth keeping in mind when choosing between the two routes.

Editorial conclusion

microsoft-365-docs suits someone who has spotted an error in a Microsoft 365 article and wants it fixed, and it suits a team that wants to track Microsoft's own guidance in version control. It is the wrong tool as a mirror, because the content is published by Microsoft and the pull request path is for corrections rather than for maintaining a fork. Check first whether the article you want to change is in this repository rather than in one of the other MicrosoftDocs repositories, and read the CLA and trademark terms before the first contribution, since both are enforced by tooling.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. MicrosoftDocs/microsoft-365-docs on GitHub
4. README