> Going to the reference guides to learn an API is like reading a dictionary to learn English.
That doesn't necessarily have to be the case. Back when I was at an IoT startup I structured the reference docs based on the order that a developer would typically use in order to get common tasks done. E.g. call this method to get the device's identifier, and then here's a list of methods that let you do stuff with the device. Chris Bush presented a similar idea [1] at this year's Write The Docs conference. His main argument is that the organization of reference docs is usually implementer-oriented. E.g. alphabetical. In many cases it may make more sense to have a user-oriented organization, one way or another.