3 ms·

> 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

> 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. [1] https://youtu.be/4OtdFEp88VI https://youtu.be/4OtdFEp88VI

gridlockd 7y ago
> His main argument is that the organization of reference docs is usually implementer-oriented. This is absolutely the biggest (and easiest) mistake people make when designing APIs. Force developers to use their own APIs as end-users - quality will improve significantly.
- Crinus 7y ago
  This reminds me of the Autotools duality: most developers hate autotools because of its unnecessary complexity but users (ie. those who want to compile the source) like it because of its flexibility (most autotool-based projects build pretty much on anything that smells like Unix), configurability and use of standard tools (shell, make) that are already installed (pretty much every other build system - like cmake, premake, meson, scons, etc - need itself installed on the user's system). So you get developers hating it and users (especially admins and distro packagers) loving it (well, packagers who have to build a lot of stuff sometimes dislike the performance).
  - AstralStorm 7y ago
    Unfortunately, there's not just one autotools but at least two major variants: libtool and direct, with 3 common incompatible versions in the wild: 2.1, 2.6, 2.13. Packagers have some trouble getting fixes to these build systems to stick. Cue Gentoo autotools.eclass with automatic application of generic set of fixes for all the brokenness of the ages.
    - Crinus 7y ago
      AFAIK this is a problem only if you want to regenerate the configure scripts. As a "user" (and packager) you should use the pregenerated configure script provided in the release.

gridlockd 7y ago

> His main argument is that the organization of reference docs is usually implementer-oriented. This is absolutely the biggest (and easiest) mistake people make when designing APIs. Force developers to use their own APIs as end-users - quality will improve significantly.

Crinus 7y ago
This reminds me of the Autotools duality: most developers hate autotools because of its unnecessary complexity but users (ie. those who want to compile the source) like it because of its flexibility (most autotool-based projects build pretty much on anything that smells like Unix), configurability and use of standard tools (shell, make) that are already installed (pretty much every other build system - like cmake, premake, meson, scons, etc - need itself installed on the user's system). So you get developers hating it and users (especially admins and distro packagers) loving it (well, packagers who have to build a lot of stuff sometimes dislike the performance).
- AstralStorm 7y ago
  Unfortunately, there's not just one autotools but at least two major variants: libtool and direct, with 3 common incompatible versions in the wild: 2.1, 2.6, 2.13. Packagers have some trouble getting fixes to these build systems to stick. Cue Gentoo autotools.eclass with automatic application of generic set of fixes for all the brokenness of the ages.
  - Crinus 7y ago
    AFAIK this is a problem only if you want to regenerate the configure scripts. As a "user" (and packager) you should use the pregenerated configure script provided in the release.