Ubuntu Wiki

So you have an experience that you'd like to document, sit down and let's talk about how to do that. It is really a very simple thing to do, but if take the time to read through this little guide your documentation and effort will be more useful to developers and user interface designers after it's complete.

Defining the experience

One of the first things that you need to do is define what you're trying to do. It needs to be contained and definable. An experience like "writing a book over 14 days" isn't going to be an interesting Wiki page for someone to read. But something like "Opening a WordPerfect file from 1995" or "Putting music on my new iPod" very well could be. It should be something that is done by a large number of users and recreatable. We would like to be able to run the same test again in the future on another release of Ubuntu to see if we're better.

Configuring your environment

In general, the desktop team is most concerned with the default install of Ubuntu on a computer. If you've installed a ton of packages from your friend's experimental repository that isn't going to effect the decisions that we make about usability as much as what we're shipping as a distribution. That being said, going through a use case with a program that's in the distribution and comparing that to one you'd like to see is very interesting. Just try to make the update as minimal as possible.

Also, you want to have a user with the minimum amount of configuration. Probably the best thing to do here is to create a new user, and log in as that user. Yes, it won't have your really cool background image, but it will create a more recreatable log that others can easily understand. This is especially important for adjustments like configuring the default application for a particular hot-plug device or file format.

Create the wiki page

You'll want to create a page in the Wiki to log your experience. You can start with the template and cut-and-paste that into a new wiki page. The template contains instructions on how to fill out the various fields with in it. If you're not familiar with writing and creating Wiki pages a good resource are the help pages in the wiki.

Logging your experience

At the most basic level you need to just write down what you see. What you need to do is describe what is going on, but in the most precise terms possible. Statements like "it took a long time" are less useful than it "took about 30 seconds." You don't need to have exact times, but more than a subjective measure is useful. This is also the case for applications and their interactions. Saying that it worked "poorly" isn't as useful as saying that it didn't work as you expected and explaining what you expected.

Lastly, be observant. Sometimes the most useful piece of information isn't the most obvious one. If you're connecting an external drive and it doesn't show up in the program you're looking at, does it show up in Nautilus? Other programs running on the machine? These provide clues for developers on where to look for ideas on what's happening.

Follow through

While defining and logging the experience are both important parts of building a good experience log, you need to take it a step further. This involves writing bugs, blueprints and posting to the appropriate mailing lists. While all of these are very dependent on the activity that you're doing it's important to make sure other people know about your work. They might have comments or ideas on how you did things or ideas about how the user experience could be better.