Improved Navigation of API Documentation
Today, I found myself down the rabbit hole trying to decipher the documentation for Feature, FeatureLayer, and FeatureLayerCollection in the API for Python. Navigating between each of the three is workable, because I have bookmarks on the left to take me right to the top of each (marked A in the screenshot).
The Problem:
All of the contents of a given module share the same page, without break. The bookmarks will take you to the header of the class, but the headers for properties & methods below that are a bit of a mess.
Each of the properties & methods (marked B in the screenshot) are immediately followed by their description and sometimes a lengthy example. Some of those examples are actually longer than the screen area, to boot, so you can be looking at the middle of an example and not even know which method it or class it belongs to.
All this together means that it's easy to get lost digging through the properties and constantly be scrolling frantically up & down to understand the context of what you're reading.
The Solution(s):
Option 1: Each of these classes gets their own subpage. You can't scroll from Feature to FeatureLayer in one continuous go; you'll have to click somewhere to navigate to the page for FeatureLayer if you want to read it.
Option 2: Add another level of depth to the navigation that lists the heading level used by B; i.e., all the properties & methods. This is what the horribly-sketched arrows at C are indicating.
Option 3: Add a table-of-contents sort of section to the top of every class that just lists the property or function, but without any of the descriptions or examples. This can then hyperlink to lower on the page where you can read more details.
Personally, my preference is Option 2, but I could live with any of these three. But the current layout is unnecessarily abstruse, especially to someone trying to look something up for the first time, without knowing what the property is called. And frankly, it's equally terrible for someone who knows more or less what they're looking for, but needs to refresh themselves on some implementation detail.
