Conversation

Notices

1. Embed this notice
   mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 12:27:33 JST 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.

   • 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

     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.

   • Embed this notice
     Kevin Marks (kevinmarks@xoxo.zone)'s status on Tuesday, 06-Feb-2024 12:27:31 JST Kevin Marks

     in reply to

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

     GreenSkyOverMe (Monika) repeated this.
   • Embed this notice
     mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 12:27:32 JST 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?!?

     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:

     in reply to
     @mcc And sample code needs to be included as part of your testsuite.
     clacke likes this.
   • Embed this notice
     Gomijacogeo (gomijacogeo@hachyderm.io)'s status on Tuesday, 06-Feb-2024 13:08:35 JST 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.

     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

     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

     clacke likes this.
   • Embed this notice
     Michael Cook (foobarsoft@mastodon.social)'s status on Tuesday, 06-Feb-2024 15:20:07 JST Michael Cook

     in reply to

     @mcc Always struggling with this.

     “Is there documentation?”

     “Here’s the list of endpoints.”

     “So no?”

     clacke likes this.
   • Embed this notice
     clacke (clacke@libranet.de)'s status on Tuesday, 06-Feb-2024 15:20:11 JST clacke

     in reply to

     • Michael Cook
     @foobarsoft @mcc "says /documentation/ right there in the Swagger UI URL"
   • Embed this notice
     clacke (clacke@libranet.de)'s status on Tuesday, 06-Feb-2024 15:43:17 JST 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

   • Embed this notice
     bassplayer (bassplayer@mas.to)'s status on Tuesday, 06-Feb-2024 15:43:18 JST bassplayer

     in reply to

     • clacke
     • Michael Cook

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

   • Embed this notice
     clacke (clacke@libranet.de)'s status on Tuesday, 06-Feb-2024 15:43:20 JST 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

   • Embed this notice
     Jimmy Hoke :tardis: (jimmyhoke@fosstodon.org)'s status on Tuesday, 06-Feb-2024 15:43:21 JST Jimmy Hoke :tardis:

     in reply to

     @mcc “The code is self documenting”

     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:

     in reply to

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

     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

     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

     clacke likes this.
   • Embed this notice
     mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 17:59:58 JST mcc

     in reply to

     • Nifflas

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

     clacke likes this.
   • Embed this notice
     Nifflas (nifflas@mastodon.gamedev.place)'s status on Tuesday, 06-Feb-2024 17:59:59 JST 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

   • Embed this notice
     Josh (jcmrva@hachyderm.io)'s status on Tuesday, 06-Feb-2024 18:00:22 JST 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

     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ᴇᴛᴛᴇʀɪɴɢ

     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

     clacke likes this.
   • Embed this notice
     mcc (mcc@mastodon.social)'s status on Tuesday, 06-Feb-2024 18:00:29 JST 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

     clacke likes this.
   • Embed this notice
     JK :prami: (jasonekratz@social.lol)'s status on Tuesday, 06-Feb-2024 18:00:30 JST 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.

   • Embed this notice
     saua (saua@troet.cafe)'s status on Tuesday, 06-Feb-2024 18:00:36 JST 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.

     clacke likes this.