Microsoft Graph documentation has a fresh new look
We’ve heard your feedback over the years that you’d like to see some improvements to the Microsoft Graph documentation experience. Today we are announcing that we’ve moved to https://docs.microsoft.com/graph, which gives our docs a fresh new look!
Searchable table of contents
The single biggest request we heard was for the ability to find things more easily in the reference documentation. With the new search box above the table of contents, you can now find all operations, resource objects, and more. For example, go type “Message” into the search box and quickly find message operations related to Outlook and Microsoft Teams.
Separate Learn and Reference docs
We heard from you that our table of contents was getting a little unwieldy, so we split our Learn topics from the Reference docs. We know that many of you access the reference docs primarily, so we made sure that important development-related topics (Get auth tokens, Use the API) are included in the reference TOC.
This makes it so much clearer to see what is supported in v1.0 and beta without lots of scrolling in the left pane.
V1.0 and Beta Version switcher
Wherever you are on the Microsoft Graph site, you can click the API Reference link in the top navigation. With the new version switcher above the table of contents, you can now quickly switch between the v1.0 and beta reference content.
Breadcrumbs
Whether you are clicking around from page to page or land on a page from your favorite search engine…the new breadcrumbs will help you to navigate to parent pages within the docs. This is super useful if you want to quickly get to a resource object. For example, I am on the Get event beta page and want to see all the properties for the event resrouce object, by clicking on the Event link in breadcrumb I immediately get there. You can also get there from the parent node in the navigation too!
Built-in feedback integrated
We’re often asked how you can provide feedback on our docs. For a few years now we have been getting feedback via GitHub Issues, but we haven’t been able to surface the feedback on the pages themselves. Now, you can use the new feedback pane at the bottom of each page to submit your feedback. This will post it in the GitHub issues list in our repository, and other readers will be able to see it on the page as well. One public user found our pre-live docs 5 days ago and already submitted some feedback for more information.
In the feedback pane, we also make it clear that if you have questions about how to use the API, your best approach is to post on Stack Overflow with the Microsoft-graph tag. If you have a feature request for the API, you should post it on UserVoice. GitHub issues should be for correcting or suggesting improvements to the documentation.
Submit your contributions
For a few years now, we’ve been accepting Pull Requests for changes to the docs directly from developers. We appreciate people providing feedback as GitHub issues, but if you’re comfortable with forking the repo, making the change and submitting a Pull Request we are ready for them!
Browser friendly
Many of you out there like to have you tablet beside your keyboard with the reference content open. The existing table of contents and general rendering of the pages was not optimal for iOS and Android. Now that we are on the docs.microsoft.com platform, you’ll be able to surf the docs from your couch without those frustrations!
Training content built in
We’ve had training content for a while, but its been buried in lab.md files within GitHub.com repos. With todays fresh look, we’ve also introduced these training labs directly into the docs! Check out the ASP.NET training lab that takes you from File | New Project all the way through to call your first Microsoft Graph API!
Share the docs!
The share button in all the docs pages allows you to tweet out useful content you’ve found. It is quite common usage pattern to send an email reminder to yourself to save it for later too!
Dark mode
For those of you who like like your docs to be easy on the eyes, we also now support Dark mode!
What’s next?
In the coming months, this experience will only get better! Now that we are live on the new docs platform, we will start to work on: localized docs transition to docs.microsoft.com; standardizing all pages to have the same content structure; adding new sections for what OData operations are supported; integrating Graph Explorer directly into each operation page of the graph; showing SDK code snippets as well as HTTP snippets; and much more.
We really appreciate all the feedback that has driven us to get to where we are today. We welcome your feedback moving forward to help us continue to make the experience better for Microsoft Graph developers!
Jeremy Thake
Senior Program Manager, Microsoft Graph
Light
Dark