Right now, we’re excited to announce a brand new, improved expertise for Python library reference documentation on Microsoft Study, previously Microsoft Docs. The brand new expertise is now accessible for all Microsoft Python libraries on Study, such because the Azure SDK for Python. On this weblog submit, we take a more in-depth take a look at the precise modifications made and the way they enhance the general expertise and accessibility of Python reference documentation on Study.
Change Abstract
The important thing modifications made to Python reference documentation on Study had been bettering the navigation expertise with the desk of contents (TOC), the group of in-page content material, and in-page navigation through the best rail. When mixed, these three key modifications significantly enhance the expertise of discovering info in Python reference on Study.
Desk of Contents (TOC)
Should you’ve used reference documentation earlier than, you’ll know that the TOC serves as a uniquely pivotal device for navigation between pages. Reference documentation, not like conceptual articles and tutorials, hardly ever hyperlinks collectively in an easy-to-follow method. Which means that the TOC is usually the one method for cross-page navigation in reference documentation, making it a key precedence for us to get proper.
TOC – Earlier than
Beforehand, the desk of contents for Python Reference documentation on Study had a redundant layer of navigation for bundle names (within the screenshot under, the azure-storage-blob node), which added confusion for customers trying to navigate deeper into the documentation. As well as, the desk of contents had bundle prefixes connected to each merchandise. This led to a cluttered expertise, with some gadgets within the TOC taking over two traces of house, additional impacting readability and accessibility.
TOC – After
The brand new TOC design removes the bundle title overview web page and trims the bundle prefix from TOC gadgets, making it simpler to scan and navigate. Should you’ve bookmarked a bundle title overview web page, don’t fear, as you’ll be redirected to the bundle overview web page robotically.
In-Web page Proper Rail
The in-page proper rail is a key a part of reference documentation, permitting you to navigate in-page and shortly leap to totally different sections.
In-Web page Proper Rail – Earlier than
Earlier than, the best rail wasn’t “sticky”, that means that when customers scrolled on the web page, the rail wouldn’t comply with them, and the complete proper aspect of the display screen could be unused house. Moreover, the best rail hyperlinks solely coated H2 content material on the web page, leading to a proper rail that didn’t make clear any main particulars on the web page. Lastly, the best rail could be collapsed past 4 gadgets, resulting in further effort from the person to see the entire H2 sections on the web page. We acknowledge this design wasn’t in step with the ways in which different Python libraries design their documentation and made updates to higher align with design patterns and expectations.
In-Web page Proper Rail – After
The improved expertise provides an individually scrollable, sticky proper rail with particulars all the way down to H3s, giving far more element into what content material the web page has. The appropriate rail moreover has energetic highlighting for the present merchandise on the display screen, making it simpler so that you can perceive your present place relative to different content material.
Parameter, Return, and Exception Group
Whereas the primary two main function modifications give attention to each general and in-page navigation, we additionally recognized a possibility to enhance in-page group as effectively. Once you’re taking a look at our reference documentation, having the ability to simply establish key info reminiscent of parameters, return values, and exceptions is essential.
In-Web page Group – Earlier than
Earlier than the updates, these particulars had been listed however not clearly separated between lessons, resulting in a complicated expertise the place it’s not clear the place gadgets began or ended. Moreover, on account of the formatting of those values, a major quantity of vertical house was used, resulting in a variety of scrolling to search out the knowledge wanted. Lastly, required parameters, default values, and keyword-only parameters weren’t clearly highlighted to comply with accessibility greatest practices, leading to further effort to search out essential info.
In-Web page Group – After
The brand new expertise organizes parameters, return values, and exceptions into easy-to-scan tables. Through the use of tables, default values, required tags, and kinds are clearly indicated. The tip result’s a cleaner and easier-to-use expertise for all builders when scrolling via our documentation.
Conclusion
Briefly, the brand new Python reference documentation expertise on Study is a serious enchancment for any developer utilizing Microsoft’s Python libraries. The brand new TOC, in-page proper rail, and in-page group modifications make discovering info simpler, with an added visible improve. We’re excited to proceed optimizing the Python developer expertise throughout all of our libraries and instruments.
We hope you benefit from the modifications! You probably have any ideas, you may go away suggestions within the Azure SDK for Python GitHub repo.
