Hi Harold, I’m glad to hear improvements are on the way, though on the whole I find the new documentation a less user friendly and occasionally confusing.
First, I’ll say that it’s quite nice that the sidebar that’s independent of the main content, where the sidebar no longer gets reset whenever I click an item (in the old docs, I’d click e.g. “job create event” in the sidebar, only to have both the main page and the sidebar scroll me up to the top).
That said, having ALL of the content on the right in an a single massive scroll page is a bit overwhelming. Notably, the “boundary” between different sections is fairly opaque, and it’s quite easy to lose your place, so to speak, when scrolling up and down (wait… what item am I looking at again?)
To the extent that you have control over these things, I’d suggest loading one page worth of content per sidebar folder (e.g. the “Webhooks” folder), and using significantly bigger header text for each header section (e.g. right now the “POSTJob create event” section header text is the same size, and subjectively smaller, given the caps case, as compared the “REQUIRED FIELDS” text below).
Additionally, as-is, clicking “view more” on an item expands it to take over the ENTIRE screen. This is quite jarring, and makes it difficult to go back and forth between the full-screen item and its surrounding context (when the user clicks “view more”, I’d suggest simply expanding the underlying content within the existing page, so that the user can continue scrolling up and down between the expanded section and its surrounding context).
This was such an issue for me that I found myself having to use two tabs: one containing the documentation as a whole, and another in which I’d expand whichever “view more” item I wanted to look at, so that I could quickly tab between the two with minimal cognitive overhead.
Finally (and I’m focused on webhooks right now), I’ll note that it’s a bit odd that the only way to understand the full webhook response “schema” is by looking at a specific example. When I see an example in documentation, I think “here’s a possible subset of possible fields,” and not “here’s an exhaustive representation of all possible fields.”
It also creates some cognitive overhead to have to constantly be scrolling between an example and the “required fields” table (which, it’s worth noting, show both required and optional fields - it’s more like a “field descriptions” table, except that only a subset of fields get descriptions).
As a final comment (and less important than the above), it’s a bit odd that the example requests are given such prominence (via the dark blue). While it’s incredibly important to have language-specific examples, I’d venture to say that most times someone is looking at API documentation, they’re examining the request / response schema or trying to understand more about a specific field, not copy-pasting an example. I generally find myself copy-pasting (language specific) examples the first time I play around with an API, but rarely after that.
It’s also worth noting that here, where examples are already used to communicate the schema (as discussed above), having another language-specific example section immediately afterwards is a bit redundant:
I’d suggest removing the blue background from the example requests, and having the full section fully minimized by default (or perhaps just show a line or two, instead of close to a dozen, as is currently the case).
I hope this helps! I think it’s great that the new format should result in fewer documentation mistakes due to redundancy, as is the case with the old; and it does solve the “reseting sidebar” discussed at the way top, which was a pet peeve of mine, but on the whole it still feels like it needs a bit more UX polish.
Cheers,
Mirek
PS: the above comments only reflect my looking at the webhook documentation.
