User experience design for APIs
blog.keras.io
User experience design for APIs
1–10 of 44 posts
Re: User experience design for APIs
#2pytorch with a keras like functional/layers API would be amazing. I'm guessing we might see that in tensorflow when keras adds support for the new eager mode.
Re: User experience design for APIs
#3Nit: Really verbose error messages like the last example are at risk of being brittle. If the API changes, there may be a failure to update the error message. This is because the messages may concern things at a distance, and may have arbitrary prose that no longer makes sense.
For example, imagine if all your error messages were basically documentation style prose. That would be a nightmare, and would set you up to a lot of error message refactoring. A better strategy is somewhere in the middle.
Re: User experience design for APIs
#4Folks interested in this would probably also be interested in:
* this talk by Jesse Noeller from PyTexas a few years ago: https://www.youtube.com/watch?v=-vZ_E1OO_PY
* the WriteTheDocs community, which is sortof a mashup of traditional technical writers and software engineers. http://www.writethedocs.org/meetups/
* the mailing list GET PUT POST (shameless plug): https://getputpost.co/overhauling-api-docs-with-gocardless-9...
Re: User experience design for APIs
#5Nit: Really verbose error messages like the last example are at risk of being brittle. If the API changes, there may be a failure to update the error message. This is because the messages may concern things at a distance, and may have arbitrary prose that no longer makes sense. For example, imagine if all your error messages were basically documentation style prose. That would be a nightmare, and would set you up to…
Links to broader descriptions in your docs are one useful tool here.
As is having a hook in github which notices that a PR updates your API schema and adds a comment with a checklist of things to be sure you've considered.
Re: User experience design for APIs
#6Perhaps "Don't change your API to something incompatible but with the same names" would be a good piece of guidance too?
https://github.com/fchollet/keras/issues/3921#issuecomment-3...
Re: User experience design for APIs
#7Programmers are so bad with this, this needs to be a more respected aspect of writing software in general. "Well, I comment everything" isn't enough. If you spent hundreds or thousands of hours on your API, but skimp on the part where you actually look at it from the users' point of view, that's such a colossal waste. You have to multiply the number of future users with the hours wasted on tedious setup hoops and learning confusing naming conventions. I look at the damage bad UX design can do to society, culturally, and I weep. A single bad decision, there, can cause millions of wasted hours.
Re: User experience design for APIs
#8I really like the error messages that Joi[1] provides. You can easily use the error.message property to give a human friendly message to the end-user and if the default options don't serve your needs you can overwrite them with custom messages.
Someone made a Joi playground a few months ago, Joi Tester[2], that makes it really easy to test your Joi schemas. If you're curious, feel free to give it a try (I'm not affiliated with the tool in any regards but I do think it's awesome).
Re: User experience design for APIs
#9Before I left Square earlier this year, I lead our design efforts on the developer API.
https://docs.connect.squareup.com/
It was really interesting work and the team was quite committed once we found the right team.
People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot.
Documentation is the obvious one but lots of other things like structuring the actual information, setting up apps, working on API explorers, look at terminology even how the endpoints are thought of and of course, how do you easiest get up and running with the API.
It was surprisingly interesting work from a design point of view.
Re: User experience design for APIs
#10Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information,…
Square has excellent developer documentation! Hopefully it's in good hands after you've left. It would suck if the quality degraded.