4 ms·

I feel like this is a bit light on data, since it's only 11 people from 3 companies using 1 (non-English) website. The takeaway, though, is consistent with wha

I feel like this is a bit light on data, since it's only 11 people from 3 companies using 1 (non-English) website. The takeaway, though, is consistent with what I've seen... people like code examples! Most people will scan until they see one, and start there. The heavy focus on API Reference in this study makes me think either the tasks were too specific, or the tutorials weren't comprehensive enough. For a good documentation site, most use cases should be covered by topical guides. Going to the reference guides to learn an API is like reading a dictionary to learn English. There's not a lot of context.

kaycebasques 7y ago
> 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.
ekimekim 7y ago
The examples also do the important job of filling in gaps that the reference docs may accidentially leave - one common one for http APIs I've found is how non-string query params are encoded (eg. this value is a list: do I give it multiple times? Do I comma-separate? Or worse: is this enum value a string or an integer?). What's especially fun is when the "code examples" for a http API use a client library which hides the actual http API, so they aren't examples of using the API at all...
noir_lord 7y ago
I’ve never understood why more apis don’t hyperlink they their code samples. It would massively improve discoverability. That and give a single large actual example of interacting with the API. That said I’ve always preferred reading code using a library over reading docs for the same library.
hv42 7y ago
> Going to the reference guides to learn an API is like reading a dictionary to learn English. There's not a lot of context. Exactly! Examples are usually the most useful thing in the documentation. Based on my experience, people go first to the examples and then read the description. I guess that's also why stackoverflow is working so well as it is basically a large library of examples.

kaycebasques 7y ago

> 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.

ekimekim 7y ago

The examples also do the important job of filling in gaps that the reference docs may accidentially leave - one common one for http APIs I've found is how non-string query params are encoded (eg. this value is a list: do I give it multiple times? Do I comma-separate? Or worse: is this enum value a string or an integer?). What's especially fun is when the "code examples" for a http API use a client library which hides the actual http API, so they aren't examples of using the API at all...

noir_lord 7y ago

I’ve never understood why more apis don’t hyperlink they their code samples. It would massively improve discoverability. That and give a single large actual example of interacting with the API. That said I’ve always preferred reading code using a library over reading docs for the same library.

hv42 7y ago

> Going to the reference guides to learn an API is like reading a dictionary to learn English. There's not a lot of context. Exactly! Examples are usually the most useful thing in the documentation. Based on my experience, people go first to the examples and then read the description. I guess that's also why stackoverflow is working so well as it is basically a large library of examples.