[ad_1]
At the moment, we’re excited to announce a brand new, improved expertise for Python library reference documentation on Microsoft Be taught, previously Microsoft Docs. The brand new expertise is now accessible for all Microsoft Python libraries on Be taught, such because the Azure SDK for Python. On this weblog submit, we take a better have a look at the precise modifications made and the way they enhance the general expertise and accessibility of Python reference documentation on Be taught.
Change Abstract
The important thing modifications made to Python reference documentation on Be taught have been enhancing the navigation expertise with the desk of contents (TOC), the group of in-page content material, and in-page navigation by way of the correct rail. When mixed, these three key modifications vastly enhance the expertise of discovering info in Python reference on Be taught.
Desk of Contents (TOC)
If you happen to’ve used reference documentation earlier than, you’ll know that the TOC serves as a uniquely pivotal instrument for navigation between pages. Reference documentation, not like conceptual articles and tutorials, hardly ever hyperlinks collectively in an easy-to-follow means. Which means that the TOC is commonly the one means 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 Be taught had a redundant layer of navigation for bundle names (within the screenshot beneath, 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 objects within the TOC taking on two traces of area, additional impacting readability and accessibility.
TOC – After
The brand new TOC design removes the bundle identify overview web page and trims the bundle prefix from TOC objects, making it simpler to scan and navigate. If you happen to’ve bookmarked a bundle identify overview web page, don’t fear, as you’ll be redirected to the bundle overview web page routinely.
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 completely different sections.
In-Web page Proper Rail – Earlier than
Earlier than, the correct rail wasn’t “sticky”, which means that when customers scrolled on the web page, the rail wouldn’t observe them, and all the proper facet of the display screen can be unused area. Moreover, the correct 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 correct rail can be collapsed past 4 objects, resulting in additional 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 right down to H3s, giving far more element into what content material the web page has. The proper rail moreover has lively 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 characteristic modifications concentrate on each total and in-page navigation, we additionally recognized a chance to enhance in-page group as nicely. If you’re taking a look at our reference documentation, with the ability to simply establish key info similar to parameters, return values, and exceptions is essential.
In-Web page Group – Earlier than
Earlier than the updates, these particulars have been listed however not clearly separated between courses, resulting in a complicated expertise the place it’s not clear the place objects began or ended. Moreover, on account of the formatting of those values, a major quantity of vertical area was used, resulting in plenty of scrolling to search out the data wanted. Lastly, required parameters, default values, and keyword-only parameters weren’t clearly highlighted to observe accessibility finest practices, leading to additional 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 top result’s a cleaner and easier-to-use expertise for all builders when scrolling by our documentation.
Conclusion
Briefly, the brand new Python reference documentation expertise on Be taught is a significant 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! If in case you have any ideas, you may depart suggestions within the Azure SDK for Python GitHub repo.
[ad_2]
