Just suddenly fell on the new Gemini API reference | Google for Developers documentation design and I’m just trying to figure out what was wrong with the old design. The new design really hides a lot of details compared to the old one. Everything was tabulated clearly and the only reason I see for the new design is Capabilities navigation section and hiding A LOT compared to old design. New design doesn’t even show both API version-specific features like the old one did. @Logan_Kilpatrick and team please how’s API reference | Gemini API | Google for Developers worst than current one? Also, for custom SDKs that implemented support for the features, now all DOC links have to be updated because the new design invalidated all previous design link references. It’s more of like the documentation designs are also in Beta that they can change anything including links.
Either the example requests are among the reasons that brought about replacement of old design so there’s no use for the Gemini Cookbook anymore, or there’s something I’m just not getting from how the new design is more beneficial than the old one which to repeat, was way clearer and exposed all endpoints in a better way.
While I’m strongly in favor of not needing the separate cookbooks anymore… I do have to agree that this makes things a LOT more complicated to read.
The nested sub-windows make for very very small and nearly unreadable windows. That some are on the side are others are inline is just confusing. We have a mix of REST and language specific documentation.
To possibly reinforce that last aspect: The example “bubbles” have a strongly non-uniform mix of languages presented. Parts of the API that were stable early on have just two languages shown, REST and Python, and more recent parts of the API have 6 or more languages shown, but systemically no longer show REST. The only language that has consistent coverage is Python. It would be very helpful to regularize the examples such that all supported languages have a tab in every example bubble. I am thinking about the large number of new entrants in the field, people that have not had exposure to many different languages over a long period of time. They get lost when they see a tidbit here they understand, and for them incomprehensible gobbledygook in the next section because their one language they are just starting to master is absent from the examples.
The example requests are welcome but the change of complete design and hiding the endpoints surely ISN’T. We’re still at a stage where we have to defend Google for using very complicated deeply nested API syntax and REST resource from old one had them keeping developers in line with usage and reference. Now I tell you, the suggestion for this new design was possibly made to push away the few developers who still hoped to mirror custom SDK from the uniformly provided REST offered by previous design. A new user who hasn’t been catered for by official SDKs from Google would just get a huge turn off if they happen to land on the new API reference page because from a glance all they’ll see are capabilities the API offers, the old one on the other hand brings curiosity into clicking each dropdown navigation item to check what is offered.
My original post was very lengthy on how they’ve discriminated and single-picked the reference page to cater for Python SDK but I had to rewrite because they tried to add other languages, which now in the actual sense places them at the point of having to include the example requests for all the SDKs and punish the users who rely on the REST versions for custom SDKs. And as you’ve observed, it must feel wonderful hiding these by prioritizing Python which had its section in old design. Maybe everyone is now required to jump to python to use the Gemini API, since it’s the MAJOR focus on the new design and others have to go through pages to try and figure out how they can mirror the API reference to their custom SDKs Google hasn’t provided yet.
The only drawback I’ve had is that the way back machine isn’t able to provide me the old design pages, because I just won’t stop getting lost with this new design everytime I load the page to look for something.
1 Like