From 6ca3bc5c3b46c143ef4113dcb2b0f9d9baf6cca0 Mon Sep 17 00:00:00 2001 From: Anton Stroganov Date: Sun, 10 Nov 2013 21:20:02 -0500 Subject: [PATCH] notes - API Design For Gem Authors and Users --- .../notes/aeon-notes.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 source/talks/api-design-for-gem-authors-and-users/notes/aeon-notes.md diff --git a/source/talks/api-design-for-gem-authors-and-users/notes/aeon-notes.md b/source/talks/api-design-for-gem-authors-and-users/notes/aeon-notes.md new file mode 100644 index 0000000..3273584 --- /dev/null +++ b/source/talks/api-design-for-gem-authors-and-users/notes/aeon-notes.md @@ -0,0 +1,52 @@ +--- +author: Anton Stroganov (@aeon) +--- + +API design for Gem authors and common folk - [@emstolfo](http://twitter.com/emstolfo), mongodb gem author + +- the constraints of designing for other programmers are stricter than designing for end user... +- gem API design is basically UX design +- httparty, rspec - succeed because they have great user experience +- arguably mongo became popular super quickly because they focus on user/developer experience +- research your user's experience + - blog posts, twitter, presentations... helps get user input about the problems they are solving + - establish trust with your users + - do not break their code... + - use semantic versioning to manage user expectations correctly! +- involve super users - people who use your gem deeply will have interesting ideas. +- UX design concepts: + - consistency + - use conventions (button colors communicate what button does) + - simplicity + - expose the minimum necessary that will concern the user... encapsulate the controls that are not vital to the user + - mapping + - the things that control other things should relate to each other clearly... confusing mapping leads to bugs and mistakes... + - example - visual mapping between stove burner controls... + +- How to apply these ideas in API design? + - consistency: + - consistent naming - variable names, option names, method names... the more different names you have, the more mental confusion there is + - consistent style - use consistent code formatting, argument chaining, etc... + - consistent behaviour - for example, how do you consistently raise exceptions... + - example: run a map-reduce in mongo, some types of jobs cannot be run on secondary nodes... + - for map reduce, it would raise an exception + - for aggregation it would silently reroute to primary node + - the behaviour is inconsistent, will confuse users. + - simplicity: + - give classes single responsibilities... this helps make the code easy to organize, and the classes easy to mentally model + - modules should also be responsible for one thing... it makes life much easier. + - only expose things to the user that they need to interact with... + - be frugal with helpers... only provide helpers for things that end user will need to use. + - example: mongo does not provide text_index, int_index, map_index, instead just provide create_index with an argument that determines index type (`create_index(type => Mongo::TEXT)`... + - design API first - start with some sample queries you want the user to write... + - Mapping: + - monkey patching is usually a bad idea... + - Side effects are surprising... if a user passes opts to a method, do not mutate them... + - requiring method chaining is impolite... it requires user to know too much about your api internals... just give them clean accessors for things they need + - good error messages are vital + - mongoid has amazing example error message that's 3 paragraphs long... problem, summary, potential resolution + - Documentation without hesitation + - anything that is odd or non-obvious MUST be documented. + - README should be short and sweet, an abstract for your gem. It's not a tutorial or a full doc. +- "Your First Ruby Gem" tutorial is great. +- Get social, user interaction is great. \ No newline at end of file