May 2012 Archives

Usability testing of CPAN modules

Al Newkirk asked me to take a look at his Validation::Class module, and I did.

But instead of asking for the directions or watching the screencast, I tried to figure it out from docs.
And I took notes of my thought process.

The result is this gist:
And here's Al's answer:

So I think it was an interesting experience, and I wish more people did this kind of thing.
Because author can't enter the same river twice; once you're familiar with your project's concepts, you tend to lose the perspective on what will confuse a new user.

You don't have to be a good writer or an experienced developer to provide this kind of feedback. On the contrary, seeing the docs for the first time is what's important to make this process work.
And the author probably won't blame you for being unreasonable -- how can he if you're admitting that you don't understand what's going on and you're just dumping your thought process?

I think if more people did this, opensource community would be a better place, and software/documentation quality would improve significantly.

PS: And if nobody is willing to do this for your project, take your friend who's not familiar with your software, sit right next to him and watch (silently!) how he suffers :)

About Vyacheslav Matyukhin

user-pic I blog about Perl.