I’ve encountered this many times where I simply don’t understand the context and use of an API based of the API documentation unless I can find an example that already utilizes it in a working project. The first thing that comes to mind is Py Torch. I’ve tried to figure out how some API features work, or what they are doing in model loader code related to checkpoint caching but failed to contextualize. What harebrain details are obviously missing from someone who asks such a silly question?

  • magic_lobster_party@kbin.run
    link
    fedilink
    arrow-up
    13
    ·
    4 months ago

    When someone writes API docs, should they assume the reader knows nothing or can they assume the is already experienced?

    It takes a lot of effort to write documentation towards newbies, at the cost of making it more difficult for already experienced to find the answer they need.

    • calcopiritus@lemmy.world
      link
      fedilink
      arrow-up
      6
      ·
      4 months ago

      Docs should be written for someone experienced in programming but inexperienced with the API. If it is about a niche subject (for example VR).

      Whenever an explanation contains something about that niche subject, you don’t need to explain everything, but maybe provide a link towards another place (for example wikipedia) that explains it.

    • ShaunaTheDead@fedia.io
      link
      fedilink
      arrow-up
      5
      ·
      edit-2
      4 months ago

      Usually API docs are tucked away inside a “developer dashboard” or whatever they decided to call it. So I think you can assume at least moderate API and web development knowlege and programming skills.