Categories
development

Your API Sucks – The ‘default’ API : REST and repeat

I’ve recently got a Fitbit, and I use the website for logging food. I noticed something about the URL scheme that I’ve seen elsewhere and it made me think about how to design default points in URL schemes.

On Fitbit, ‘/foods/log’ opens the page for today’s food, and there are controls to navigate to yesterday and beyond, when the URL changes to ‘/foods/log/{date}’. So far, so simple. But when I navigate back to today, the URL still contains the date. My browser is set to reload pages from last time, so the first URL always gives me today. The second, doesn’t.

Should we set defaults that can change based on context? Or should the default redirect to the appropriate context? Or should we always be explicit? Should default URLs automatically redirect?

If I load the page before midnight but submit after, the screen and the URL indicate different dates. What is the right date?

UPDATE: The new Fitbit logging page, which appears occasionally at `/foods/log` takes the date as an explicit parameter (it’s a drop-down on the page), so no longer has a default. This is a much better strategy for submitting data

Categories
development ux

Work hard to make things simple

Bowling Alley

“Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius — and a lot of courage to move in the opposite direction.” ERNST F. SCHUMACHER

It’s easy to write software. Ask users what they want (or even better, observe them and discover their problems), find a clean, user-friendly solution, build it and deliver it, for free, with no ads.

And you make a success of it, so you add more features to see off the competition, or to disrupt a new market. Google built Gmail, then added automatic categories, and Smart Replies to make it easier to process your messages. And they also added Wave, Buzz, Google+, Talk and others, to demonstrate other ways to connect and communicate, for places where email doesn’t work so well. So many new features, new things to learn, spinning out from that new core.

And yet Gmail remains popular, the rest, not so much.

It’s easy to add features. With a bit of work, you can even add them seamlessly without adding another menu option that your users will never see.

But what’s your plan to remove options, to streamline your code? How do add a new feature that’s easily discoverable and useful? How can you be smart and subtle?

What is your simplification strategy?

Categories
development

The frustration of confounding expectations

Icons on the microwave : heat water with a spoon in it. There is a glass of water without a spoon with a cross through it.
Spoons in the microwave

After years of being told no metal in microwave, it still feels too weird to follow the instructions on my new microwave to use a spoon when boiling water. There’s a sticker telling me I have to add a spoon when microwaving water but I don’t see myself ever doing that because the “no metal” is so ingrained, and I’ve seen plenty of lightning videos from people who have done it.

A lift control panel with a numeric keypad and the letter C in the display
Abstraction in lift design

This picture is from the lifts at the local hospital. You press a floor number (rather than up/down) and the display responds with a letter telling you which lift to catch. This additional abstraction confuses many users, as I discovered helping people use them as I was taking a coffee break.

I see the same thing on a lot of websites. Those “cool” websites that break scrolling by moving things sideways or zoom in as I scroll down. SPA sites that break the back button. Using outlook web access on a mobile browser is painful. I keep getting the “Are you sure you want to resend?” or the login prompt when I try to go back to my message list from an email.

I’ve never been a great visual web designer, I’m definitely a function-over-form type, but I’ve always started with the principles that came to be known as progressive enhancement. Make it work in the simplest way, and add the bells and whistles on top of a strong, accessible foundation. That foundation has shifted from HTML, to HTML+CSS+JS, to TSX in my latest projects, and from desktop to mobile throughout, but it is always based on the basic principles of text and forms : easy to read, easy to follow, and works the way you expect it to.

If you’re trying hard to stand out by breaking expectations, what are you trying to hide?

Categories
development ux

User Experience : A quick introduction for developers

The following is an internal summary I wrote for a team that no longer exists, summarising a number of references from UXScotland, various book and blog posts. It extends the thoughts from my Pecha Kucha talk. For more details, please refer to the links throughout and the references at the bottom. The context here is consulting and long-term B2B projects, but some of these discussions are more widely relevant.

User Experience : Project considerations

User experience is about making sure we are solving the right problems in the right way. It is the intersection of design, users, and context. Context here is a combination of one or more of the device in use, the user’s location, any social cues such as nearby friends, and anything else that may be available from sensors or historical information.

vennux

In many cases, the requirements we have are assumptions (e.g. what users want is Facebook integration). Where the benefits of a requirement are unclear, we should treat it as an assumption to be tested. Embrace data, and analyse it.

At the requirements stage, we need to make sure we are solving the right problem (pretotyping : “building the right *it*”), and that our chosen design helps the user to solve the problem without frustration (i.e. prototyping the design, rather than the implementation, with wireframes/sketches).

In user testing, particularly in an agile development, we can refine those ideas by seeing how well the implementation solves the problem, by testing with users. We can also test deployed code by analysing heat maps and http logs to see what users are doing to inform further tests and the assumptions that feed into further design cycles.

In a Lean/Agile project, we need to be explicit about our assumptions about the user and test them at every stage of the development to ensure that we always meet user needs.

cycleofux

How does UX fit in our process?

Stakeholders

A system that supports user’s need effectively will need to understand that the user is a Stakeholder in the process. Whilst the users themselves may not be directly involved in the generation or review of design artefacts, there should be a user representative, either a super-user on the customer side, or a 3rd party researcher who has determined user needs, and has authority to verify any proposed solution and high-level requirements against those needs.

Functional Requirements

Personas / Typical Users

A persona is an abstraction of a system user. In a simple system, there may be only one type of user, but more sophisticated systems will typically have users and administrators, and may have multiple classes of each. A persona is defined to encapsulate the types of tasks a specific user may wish to perform, and any limitations that may be imposed (for example, administrators may be able to install specific browsers or client software, but members of the public using the system must be supported across multiple browsers at multiple screen sizes).

User Journeys

Each persona will have one or more tasks they wish to perform in the system. A User Journey describes the tasks as a series of steps that a specific persona will follow in order to achieve that task.

Consider the tasks that a user wants to perform. See also BDD – design from user in.

E.g.

User wants to process a case:

  • User logs in to the system
  • User selects case from their task list
  • User reviews latest document
  • User finds agent for case, and calls to discuss
  • User adds comments to case
  • User saves case and returns to their task list

This process may identify a new use case (“Display task list”), and specific actions that need to be defined within a use case (“Display latest document” and “Display agent contact details”)

The User Journeys provide the context between the Stakeholders (and User Types therein) and the Use Cases. Each User Journey will link to one or more Use Cases, but some Use Cases may not have an associated User Journey (nightly payment processing, for example).

User feedback

If the solution is replacing or improving an existing system, the best source of information on the current system are the users. The requirements capture process should take into account both the tasks that the users perform and gather feedback on any areas of frustration. The prioritization exercise should consider these improvements as well as new functionality.

Testing

As well as testing the Use Cases for functional acceptance, the FAT/UAT process should also test that the final system supports the User Journeys defined up front.

On-going support

Where projects have regular support meetings, the input of users has been valuable in identifying problems areas and possible changes. When on-going service delivery contracts are defined, SDMs should consider whether ongoing user feedback is appropriate as part of the planning and scoping of releases within that framework.

Questions to ask

  • Have the requirements been tested on users? If not, why not? (Are these the right requirements?)
  • Will users be given the opportunity to provide feedback on these through the development? (And if so, how, when and where?)
  • What user outcomes are we trying to achieve with the release? These may not be requirements that we put a cost on, but an expectation that we can measure against to show improvement – we would need to communicate this appropriately.
    • E.g. minimise clicks to access the 5 main functions
    • E.g. reduce time-to-complete for function x, y and z by 10%
    • E.g. Align existing UI with iOS and Android norms
    • E.g. Increase usage of function z by 5%
    • E.g. 99% AAA compliance
  • Who represents users on the project team?
    • How many user types do we need?
    • Can normal users and administrators share UX, or are their goals divergent? – different apps, different ASP Areas, different branding, …
  • What platforms and form factors need to be supported/tested?
    • Does each platform need a native UX? If native app, probably yes, if web app, maybe.
    • If mobile, do we need to adapt to context : location/orientation/communication with nearby devices/…
    • If social, do we need to adapt to context : can I approve my own work?/who’s online/recommendations/who’s nearby/…
  • Do we, as developers, have any input to the UI design? If not, why not?
  • Have the designs been tested on users? If not, why not? (Does the UI fit user expectations?)
  • Do we have appropriate guidelines for the appropriate platform, and are they listed in the requirements and estimates?

Potentially useful resources

 

Categories
development ux

Little UX wins #littlejoys

I’m no expert in user experience. So I’ll let others talk about the personas, the end to end journey and bringing joy. I want to talk about the details.

Those papercuts that slice away at you, that just make things a bit more work. The things that spending 15 minutes watching users makes you scream at yourself for putting your users through it.

But it doesn’t just affect technology. Here’s a list of papercuts I’ve noticed, either because one company has fixed them, highlighting the pain that everyone else puts you through, or because they annoy me. Reflect on your experiences as a user. What delights you and annoys you?

Things I like

  • Waitrose Meat in foil trays store the sachet in the cardboard cover, outside the foil tray, so no meat juice on them. This is a great example of separating concerns so that the raw, unsafe meat never comes in contact with the sauce until it has been cooked to make it safe.
  • Double tap to wake. The on button on many phones is small, and often hard to reach when on the table. Phones that allow a full screen action to wake take advantage of Fitts Law and their large screens to make that common action much quicker.
  • Lenovo N22 carrying handle. Many people carry their laptops without a bag. When you have a cheap, light, knockabout laptop, embrace it, and give it a handle. Bonus: teachers can carry many at once.
  • There’s also a bundle of wonderful examples here: UX out of electronic spaces http://uxpa.org/upasiteredirect/index.html/uxmagazine/lets-get-physical/?utm_content=bufferea7eb&utm_source=buffer&utm_medium=twitter&utm_campaign=Buffer

Less good

  • In my house, there are some lockable windows and some button operated (for fire safety upstairs)). On the button windows, you push and then turn. On the lockable ones, you turn the key to release the button, then turn. Every time, I push the button to open those windows, see the locked window depressed and think it’s unlocked. Every. Bloody. Time.
  • Something that needs better feedback rather than relying on transferable knowledge that many people are bad at : estimating size. Why does no microwave rice have a visual indicator of 2cm for the tear? So many packets have “tear here” and printed perforation. Why not “stop here”?

What papercuts have you seen, and what user experience interactions give you joy?

Categories
development ux

Always be finished

I’ve been living on a building site for a while, at home and at work. The work at the office above ours was ambitious, chaotic, noisy, messy and overran. It was a challenging project, turning a “derilict” into a funky new office.

Home was a simpler proposition, a greenfield site, with a well tuned team putting up a batch of similar houses. Each house in the project was a clear finishing point. The work was completed on or near budget, although there have been many bugs in the finished product. Nothing to break the deal, but enough to be annoying, and a few that need serious attention before things get worse.

The most interesting thing for me however was complete the overall project looks. At each stage the customer perception is paramount, so roads and car parks are built and finished in places where in a few months they’ll be ripped up to put houses on because that’s the most central place to put the marketing suite so customers can see their house quicker.

And the perfectly manicured lawns at the show home will be ripped up to build a driveway for the garage. And the landscaped street gables get cut back to move the marketing suite. But at each stage there’s a clear “here’s what’s being built” and “here’s the rest” even when what looks complete is not the final vision.

The perception even extends to certain rules for residents to ensure consistent façades and a complete presentation, with no unsightly trade vans, for the entire site until the last one is sold.

When you build software, how finished do the “temporary” solutions look to the customer and the developers. Do they look hacked on, unreliable and in desperate need of a bug fix, or do they look finished and smooth to the end user, with a few backlog tickets describing what it really should do. No hint to users or competitors that something is about to change.

It’s not enough for everything you release to be complete and tested. If users can see the cracks, it will colour their impressions. Fix the snags and delight your users.

Categories
development

Accessible for everyone

I don’t know if you’re familiar with Isofix child seats, but you spend all your time figuring out how to fit it correctly in one car, then you have to switch to another car and it just doesn’t seem to fit the same way. (Browser manufacturers, take note).

A safely fitted child seat has green flashes that appear to show that the seat is locked into position, and they’re easy to check by inserting your eyeballs in the 3cm between the edge of the seat and the car frame (I admit this is slightly easier in a 5-door car where the frame is removable via a hinge).

For those without detachable eyeballs, this can be a challenge.

But the car seat we have has a nice little accessible touch. The green flashes are hook shaped, and recess into the seat when the seat is unlocked, so if I can feel a hook on the side of the seat, I know that the seat is securely locked.

I don’t know if the designer deliberately chose to make the safety catch non-visually accessible, but I am very grateful that they did. It has saved me a lot of sore heads and worry.

I assume that the designer in question was not the genius who decided that websites with infinite scrolling should have footers. *scroll down* ah, site map *click* *new content loads* *wrong page opens*. That designer should find a bothy somewhere and stay away from computers for the sake of everyone else.

Be accessible. Looking snazzy is one thing, but if you really want to be appreciated, think about the little touches that make the interactions wonderful, and make something that’s otherwise impossible, easy.

Categories
development ux

Wings of desire – future-proofing software architecture

(Note: this was originally posted on a since-archived company blog, so apologies for those who’ve read it before)

Architects are never quite sure how their buildings and common spaces are going to be used once real people move in. Just as software developers are never quite sure how their software is going to be used. Architects design openness into their designs in many ways, to allow spaces to be re-configured to a certain extend, and one important idea that they have used is leaving open areas unconstrained so that “desire lines” can form. These represent the most trodden paths, the favourite routes, across a space. Once these have settled down, months after the users have moved in, they can be formalised. Desire lines on grass are reinforced with gravel tracks. Desire lines in offices may be re-carpeted, or defined with furniture.

I’ve seen a few blogs talk about using desire lines to build web sites, using logs to determine which content was most used so that a re-design can highlight those areas or make them easier to use, and reinforce the way users are interacting with the site, but it struck me today when discussing new requirements with a client that desire lines are at the heart of many of the business processes that we model.

It is a rare occasion when a client comes to us with a fully formed idea of everything they want, so design and requirements capture is an intrinsic part of the development process, but there are many areas where the client doesn’t have an idea because no-one has tried it yet. There’s a new business process because they have a new class of user, or new laws to follow, or because the system and the business process it supports are being built together.

It’s tempting, as developers, to look for rigid rules, to find the underlying logic and find ways to make business rules concrete and algorithmic. It can also be the wrong thing to do. Have you ever had a customer or a user complain because the software does the wrong thing? When they have to work around the software to get the job done because the software is too inflexible? Not because the business process is inflexible (there’s not much we can do about red tape), but because the software enforced a business process that was incompatible with the best way to do the job.

Imagine a system where there is an approval process. There’s a screen, with a big “Approve” button on it. We know that  the requirements gathering process has identified that there are some business rules that need to be in place before approval. We know for sure that the Approver has to be a different user from the one who started the process, and in order to approve, the user has to add a comment for the audit trail. We believe there should be a time limit, but no-one knows what it should be, we know some other tasks need to be completed, but we’re not sure what. So don’t nail them down. Let the user add the comments to say that the time has elapsed. Let the audit record that the other tasks have been done. In 6 months time, the desire lines will be obvious. There will be a process. That’s when you update the screen.

We’re not mind readers or fortune tellers, so when we find ourselves looking at a problem we’re trying to nail down business rules that don’t quite make sense, or aren’t quite firm enough, maybe it’s time to step back and see if there’s a way to let users define their own desire lines where they get to decide how to get the job done, and once they understand the rules, we can always enforce them in the next version.

Categories
code development programming

Usable APIs follow-up

Following the Usable APIs guided conversation at CodeCraftConf, I wanted to capture some of the thoughts that came out.

Starting an API (as a user or a developer)

  • Does the API documentation include examples of usage (i.e. have they thought about the client)
  • How mature is the API?
  • How well maintained is it?
  • How long does it take to get to the first success (e.g. 200 OK – assuming success doesn’t mean error).
  • What’s the versioning policy?
  • What’s the contract?
  • What’s the shape of the data?

Changing and retiring APIs

  • Never, ever, ever, change the endpoint.
  • Give as much notice as possible of changes (and never negative notice).
  • Provide migration guides to clients, or automation scripts, such as the Python 2to3 migration scripts and guide.
  • Be proactive – there was an example given of a web API (I can’t remember which one, sorry) that changed their endpoint, and created a bot that searched Github for usages of the old URL, and submitted pull requests for the new usage.
  • Deprecate, then kill, once usage falls below a threshold.

Foolproof APIs

Isolation and proxies

  • Log everything to detect unreliability.
  • Make sure proxies are kept up to date with the underlying API, and fail gracefully when the API changes.
  • Expect failure.
  • Data is key – don’t give up more than you have to.
  • Make sure, as a server writer you understand the client, and the network.
Categories
development programming ux

Developers are Users Too : Why the User Experience of Your API sucks #yourapisucks

Many thanks to those of you who came along to my talk on why your API sucks. There were some great discussions during and after, and I hope I’ll be seeing slightly fewer reasons to tear my hair out in the near future.

A few things that people mentioned that I want to discuss again, as they’re not on the slides.

APIs still need a view model

There was a question about the API view of your data vs the database view. A good API still follows MVC principles. Just because a View is written in JSON instead of HTML doesn’t make it a model. Isolate it, because otherwise a database change is an API change. You can use automappers to save you having to write convertors, but always create a view for your API so you can handle versions and create consistency.

There was also a big discussion on how deep the hierarchy should be, particularly relating to data obesity. And it’s a different tradeoff if you’re optimising for poor latency, where larger packets with redundant informatio make more sense, or timeliness where small packets that can be built and parsed quickly are preferred. It all depends on your users. It may be the case, as the Trello API does, that returning the deep hierarchy is a request option so that the user can decide.

User Experience doesn’t always mean asking the user

Developers will ask for lots of things that aren’t useful. Sometimes you need to discover what the user needs are. Maybe it’s a test-first design. Maybe it’s a loosely typed API to help you discover what users want to do (think Google search vs Yahoo’s hierarchy – Google is more loosely types so was more likely to return odd results, but Google had lots of data on what people were searching for that it could learn from).

Link suggestions from the audience

Thanks for these suggestions. I’ll have to try them out myself, so I’m putting them here without warranty.

Kong – to consolidate your APIs, and create the polished surface that doesn’t expose the dirty, inconsistent history behind it.

RAML – to design a typed RESTful API up front so you know what it will look like.

Heroku’s HTTP API design guide

Slides from Google Docs

Developers are users too

Slides from Slideshare