Webhook event documentation inaccuracies for the delivery model

The documentation for the currentDelivery field of the driver update event has the following issues:

  • The transportType field should have an inner code field listed.
  • The packageType and cancellation fields should be listed.

Broadly speaking, the documentation for [driver update event].data.job.currentDelivery should be consistent with the documentation for [delivery update event].data and [job update event].data.currentDelivery (I’m assuming you’re using the same model for all three on the backend - at least, the resulting JSON data follows the same schema for all three).

Some specific nits:

  • A number of fields are listed as “required” for [job update event].data.currentDelivery, whereas all delivery fields are listed as optional elsewhere.
  • It’d be nice if the order that delivery model attributes are listed would be consistent across the three places the delivery model is used. For instance, for the job update event, trackingUrl is the second delivery model field listed. For the “driver update” event, it’s the 8th field listed. For the “delivery update” event, it’s the 9th field listed.

Hello @mirek,
Thank you for your message!
We have released a new version of the documentation, that you can find here.
Let me know if the examples suits you better, or if we can improve it !

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.


PS: the above comments only reflect my looking at the webhook documentation.

Hello @mirek,
Thank you for your long and very described post!

Unfortunately, most of your feedbacks are related to the tool we are using, which has some limitations that we can’t really modify or customize (view more, text size…).
We will anyway continue to follow Postman new features in order to improve the documentation.

For your point about examples, you can use the “double column mode” in order to display the examples on the right, and the documentation on the left.

Cheers !

Thanks @Harold, makes sense, and that’s a good tip. All else held constant, then, from a (read: this) developer’s perspective, the old documentation framework is much preferred to the new. That said, understood if this decision is out of your control or there are other considerations in play. In any event, thanks for the preview!