In the article “What do you do when there is no documentation?” Chris Hartjes wrote about his attempt to use the Auth component in CakePHP for which almost no documentation exists. As I wouldn’t call Chris a newbie, it made me think. Is the missing documentation really the problem? Or could it be something else that makes it hard to use the component?
That’s when I realized it could be a usability issue. And that the “user interface” of the component is simply not understood by the users… Anyway, this post is not about possible problems of the Auth component.
What I want to talk about is, as the title says, usability-driven development. If you hear “usability”, you probably associate it with user interfaces and how people interact with them. And so usability-driven development will probably deal with making better user interfaces. That’s correct. But it is not about user interfaces like web pages, it is about “user interfaces” of code components.
I know, it sounds a bit strange. But on an abstract level you can look at the public attributes and methods plus the comments as the user interface of a code component. And the programmer, who uses the component, interacts with this user interface. You may imagine a component as a beverage vending machine: methods are buttons, method names are the button labels, and comments are descriptions of the buttons. I know, this thought model is a bit inaccurate, as parameters and attributes are missing. But it shouldn’t matter.
By doing some thought experiments with our imaginary beverage vending machine we can come up with the following conclusions:
- too many descriptions suck as nobody likes to read much before he can use something
- good button labels help to avoid unnecessary descriptions
- too many buttons suck as it makes it harder to find the desired button
- the order of buttons matters as it is faster to find the desired button when the buttons are ordered
- as it is a beverage vending machine it shouldn’t provide food
These conclusions can be easily translated back to code. By doing this we will see that a lot of code is not optimal from a usability point of view…
To get more concrete results (e.g. whether two methods without parameters are better than a single method with a parameter) we could introduce some metrics into our thought model, e.g. the time it takes to accomplish something.
Ok, what can you do to improve the usability of your code?
I think the most important point is to get a mindset that your code components are user interfaces for others and that you want to provide a good user experience to them. So you will design your components differently (compare it with the iPod vs. traditional MP3 players).
It is also a good idea to follow good coding practices like testing and refactoring.
And last, but not least, you could do usability tests. Give your component to someone else who never used it and let him accomplish a task while you watch. It may give you some good insights into what sucks with your component ;-)
Ok, I hope it was not too confusing. And maybe you will now look differently at your code ;-)