Usability-driven development
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 ;-)
i definitely agree with u,
code should be written for its purpose, if it is component its purpose is easy use for users (programmers)
Heh, I’ve come to the same conclusion(s). the interface of code is very important, and not just for others, for yourself as well.
I agree that a good, consistent public interface is essential for a code component to be easily adopted.
I also think that bundled unit tests are great. If I decide to hack something I like to know that it hasn’t broken anything.
Since you open your post with a reference to the “no documentation” post, I cannot keep my mouth shut. You claim “[...] you can look at the public attributes and methods plus the comments as the user interface of a code component. [...]” I couldn’t agree more. But why do you exclude documentation when you include comments? Proper documentation is as good a part of good software as helpful comments are. An undocumented API is a user interface without any help menu and no tooltips. Documentation is a critical component of any software, be it for users or for programmers.
@Leif: I didn’t include documentation because documentation is decoupled from the code. If I work with a component in my IDE, I have to leave the IDE to read the documentation. So documentation exists on its own.
Personally I think a good user interface comes without any help menu and no tooltips. And so an undocumented API would be the ideal API we should aspire. I know, it sounds a bit illogical and like an idea of a lazy guy who doesn’t want to document an API, but I think writing such an undocumented API requires more work if your goal is a good usability of the API.
I agree with you that documentation is important, especially to provide the “big picture”, or in the form of tutorials.