GNU social JP
  • FAQ
  • Login
GNU social JPは日本のGNU socialサーバーです。
Usage/ToS/admin/test/Pleroma FE
  • Public

    • Public
    • Network
    • Groups
    • Featured
    • Popular
    • People

Conversation

Notices

  1. Embed this notice
    mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 12:27:33 JST mcc mcc

    People who design APIs. I am begging you. It doesn't matter how "simple" or "intuitive" or "elegant" your API is. You need to include sample code.

    In conversation about a year ago from mastodon.social permalink
    • Haelwenn /элвэн/ :triskell: and clacke like this.
    • Embed this notice
      Travis F W (travisfw@fosstodon.org)'s status on Tuesday, 06-Feb-2024 12:27:30 JST Travis F W Travis F W
      in reply to
      • Kevin Marks

      @KevinMarks @mcc I have given up on so many source repos where the build command failed to compile or run the example, and it just isn't quite worth it to try to troubleshoot a problem *before* I try it out.

      In conversation about a year ago permalink
    • Embed this notice
      Kevin Marks (kevinmarks@xoxo.zone)'s status on Tuesday, 06-Feb-2024 12:27:31 JST Kevin Marks Kevin Marks
      in reply to

      @mcc so much this. Sample code should run and do something that makes sense.

      In conversation about a year ago permalink
      GreenSkyOverMe (Monika) repeated this.
    • Embed this notice
      mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 12:27:32 JST mcc mcc
      in reply to

      Another thing I am begging of people who make APIs: When you include sample code in the docs, include the "using"/"use"/"import"/"#include" statements. Please. Please. I just pasted this inline sample code https://mlem.ellpeck.de/articles/ui.html#setting-it-up into my hello world program, and it's failing because the symbol "UntexturedStyle" could not be found. "Are you missing a using directive or an assembly reference?", asks dotnet. Yeah, probably?? because you didn't tell me what using directives I needed?!?

      In conversation about a year ago permalink

      Attachments

      1. No result found on File_thumbnail lookup.
        MLEM.Ui | MLEM Documentation
      clacke likes this.
    • Embed this notice
      Haelwenn /элвэн/ :triskell: (lanodan@queer.hacktivis.me)'s status on Tuesday, 06-Feb-2024 13:03:56 JST Haelwenn /элвэн/ :triskell: Haelwenn /элвэн/ :triskell:
      in reply to
      @mcc And sample code needs to be included as part of your testsuite.
      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      Gomijacogeo (gomijacogeo@hachyderm.io)'s status on Tuesday, 06-Feb-2024 13:08:35 JST Gomijacogeo Gomijacogeo
      in reply to

      @mcc This is something the UNIX man pages got right nearly 50 years ago. The synopsis included linker flags and #include files needed to call any routine.

      In conversation about a year ago permalink
      Haelwenn /элвэн/ :triskell: and clacke like this.
    • Embed this notice
      mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 15:19:29 JST mcc mcc
      in reply to

      "But it's obvious" I'M READING THE "GETTING STARTED" DOCUMENTATION. OBVIOUSLY I HAVE NO BASIS FOR COMPREHENDING WHAT IS OR ISN'T OBVIOUS

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      Michael Cook (foobarsoft@mastodon.social)'s status on Tuesday, 06-Feb-2024 15:20:07 JST Michael Cook Michael Cook
      in reply to

      @mcc Always struggling with this.

      “Is there documentation?”

      “Here’s the list of endpoints.”

      “So no?”

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      clacke (clacke@libranet.de)'s status on Tuesday, 06-Feb-2024 15:20:11 JST clacke clacke
      in reply to
      • Michael Cook
      @foobarsoft @mcc "says /documentation/ right there in the Swagger UI URL"
      In conversation about a year ago permalink
    • Embed this notice
      clacke (clacke@libranet.de)'s status on Tuesday, 06-Feb-2024 15:43:17 JST clacke clacke
      in reply to
      • Michael Cook
      • bassplayer

      @bassplayer They can be done well, with excellent examples and guidance and all, but they can also be just a list of endpoints, and depending on the backend the spec may or may not match the implementation.

      @mcc @foobarsoft

      In conversation about a year ago permalink
    • Embed this notice
      bassplayer (bassplayer@mas.to)'s status on Tuesday, 06-Feb-2024 15:43:18 JST bassplayer bassplayer
      in reply to
      • clacke
      • Michael Cook

      @clacke @mcc @foobarsoft I've always preferred swagger interfaces if they are done well

      In conversation about a year ago permalink
    • Embed this notice
      clacke (clacke@libranet.de)'s status on Tuesday, 06-Feb-2024 15:43:20 JST clacke clacke
      in reply to
      • Michael Cook
      • bassplayer

      @bassplayer In principle I agree with you, and I think a form of executable documentation is the best documentation. An excellent Swagger UI is a great troubleshooting and teaching tool.

      But there's no guarantee, and it's easy to say "documentation? oh yeah we have a swagger", which may be glorious or it may mean almost nothing.

      @mcc @foobarsoft

      In conversation about a year ago permalink
    • Embed this notice
      Jimmy Hoke (jimmyhoke@fosstodon.org)'s status on Tuesday, 06-Feb-2024 15:43:21 JST Jimmy Hoke Jimmy Hoke
      in reply to

      @mcc “The code is self documenting”

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      petterroea :verified: :archlinux: (petterroea@infosec.exchange)'s status on Tuesday, 06-Feb-2024 15:43:25 JST petterroea :verified: :archlinux: petterroea :verified: :archlinux:
      in reply to

      @mcc honestly I don't even trust api docs as they are often incomplete.

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      argv minus one (argv_minus_one@mstdn.party)'s status on Tuesday, 06-Feb-2024 17:59:57 JST argv minus one argv minus one
      in reply to
      • Nifflas

      @mcc

      This right here is why Rust compiles and executes example code in docs, to make sure that it actually works.

      Sadly, it can only do this for code examples, not English prose…

      @Nifflas

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 17:59:58 JST mcc mcc
      in reply to
      • Nifflas

      @Nifflas The sample code is also wrong. I'm gonna have some bugs to file >_>

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      Nifflas (nifflas@mastodon.gamedev.place)'s status on Tuesday, 06-Feb-2024 17:59:59 JST Nifflas Nifflas
      in reply to

      @mcc Yeah, that stuff is super annoying. A good thing is, in Visual Studio, you can right click the thing and it'll show you which namespaces it can be found it. Well, for C# at least.

      But obviously you shouldn't have to, I completely agree that ofc it should be in the sample code.

      Edit: Also, wow, that sample code really likes putting "this" before stuff :O

      In conversation about a year ago permalink
    • Embed this notice
      Josh (jcmrva@hachyderm.io)'s status on Tuesday, 06-Feb-2024 18:00:22 JST Josh Josh
      in reply to

      @mcc The dotnet space is frequently terrible about this.

      "Visual Studio will automagically fix it for you!"
      - no, not always
      - I don't use VS

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      Mᴀʀᴋ VᴀɴᴅᴇWᴇᴛᴛᴇʀɪɴɢ (brainwagon@mastodon.social)'s status on Tuesday, 06-Feb-2024 18:00:24 JST Mᴀʀᴋ VᴀɴᴅᴇWᴇᴛᴛᴇʀɪɴɢ Mᴀʀᴋ VᴀɴᴅᴇWᴇᴛᴛᴇʀɪɴɢ
      in reply to

      @mcc I also think it would be good if the very first thing you find on their website is a high level description of what the API does, and why you might want to use it.

      It's amazing how so few actually do. It's like they posted a video on youtube which 1000 people have seen, so you must have heard of it. https://youtu.be/pRz2icpq5Sc?si=Khezbq8tbY-xNU8j

      In conversation about a year ago permalink

      Attachments


      1. You Can Do Anything - Saturday Night Live
        from Saturday Night Live
        Subscribe to SaturdayNightLive: http://j.mp/1bjU39dSEASON 37: http://j.mp/1e9Lb42Talk Shows: http://j.mp/170pPA5On You Can Do Anything, the hosts welcome Int...
      clacke likes this.
    • Embed this notice
      mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 18:00:29 JST mcc mcc
      in reply to
      • JK :prami:

      @jasonekratz I mean, it would be nice to have one of each. Ideally. I often run into problems where I wanna make something really simple, and the only sample is very complex and it's not clear what is separable lol

      In conversation about a year ago permalink
      clacke likes this.
    • Embed this notice
      JK :prami: (jasonekratz@social.lol)'s status on Tuesday, 06-Feb-2024 18:00:30 JST JK :prami: JK :prami:
      in reply to

      @mcc lets be more specific - it should be *good* sample code. Too often I see these ridiculous, absolute bare minimum examples. Make sure the samples really give good working code, not just crap you're throwing on last minute. Of course thats why so many APIs have shitty samples/docs. It's not easy nor quick.

      In conversation about a year ago permalink
    • Embed this notice
      saua (saua@troet.cafe)'s status on Tuesday, 06-Feb-2024 18:00:36 JST saua saua
      in reply to

      @mcc 100% agree. IMO sample code should be treated like test code: if it doesn't compile and pass, then the build/release must fail. Few systems have the necessary tooling, but I've seen it frequently enough to know that "can't be done" isn't the real reason this isn't more widespread.

      In conversation about a year ago permalink
      clacke likes this.

Feeds

  • Activity Streams
  • RSS 2.0
  • Atom
  • Help
  • About
  • FAQ
  • TOS
  • Privacy
  • Source
  • Version
  • Contact

GNU social JP is a social network, courtesy of GNU social JP管理人. It runs on GNU social, version 2.0.2-dev, available under the GNU Affero General Public License.

Creative Commons Attribution 3.0 All GNU social JP content and data are available under the Creative Commons Attribution 3.0 license.