Blogs

My previous post had much more success that I had ever imagined, which is good because it means that there is a lot of interest in the community to have a better wiki portlet. Also one of my conclusions after reading the comments is that there is a renewed interest in Liferay's bundled wiki portlet.

This purpose of this second post is to explain, and show with screenshots, a set of changes that I made to such portlet to solve what I saw as it's weakest points. Also, I wanted to use this opportunity to show what a difference could be made by just making usability improvements. That's right there not a single new feature, it's just the same old wiki but the results speak for themselves. I must confess that I was myself surprised by them, and now I can't wait to start using the portlet in liferay.com ;)

Conquering the first impression

One of the problems of the wiki portlet is that it gives a quite bad first impression. And it does so because it looks nothing like a wiki and uses concepts (such as nodes) that make no sense to the average user. Here are two screenshots of the first impression that a user gets when using the portlet (before and after creating a node)

How could we solve this? Looking at other wikis they all have one thing in common: after installation the first page is a wiki page. In fact all most wikis have is wiki pages, even the administration screens are wiki pages. I didn't want to go that far, but it was clear that we needed the first screen to be a wiki page. Here are the steps I took in order to achieve that:

1. The initial view of the portlet should always be view of a page (the /wiki/view_page mapping of struts), so I renamed the current initial view as 'Administer Nodes' (/wiki/view_nodes in struts-config) and made the view of a page the initial view (renaming it as /wiki/view)
2. That leads to a problem when the portlet is first used: there is no page yet, neither a node to put it on (in Liferay's wiki all pages belong to nodes, more on that later). The solution is easy: if the number of nodes is zero, create a default one, with a default page inside.
3. If no node or page is specified the (as it happens when the user first goes to a page with the wiki portlet) portlet just shows the FrontPage of the first node

Here is the result:



That sure looks much more like a wiki. Some more changes that I did and can be seen in the screenshot are:

• Make the title bigger, place it under the search box and remove the breadcrumb
• Aggregate all of the actions that can be performed on the page in a single "actions" menu to reduce visual clutter and leave more space for what really matters: the page contents

I wasn't sure if I should have a template with default contents for that page. But thought that it would create all short of difficulties regarding internationalization (remember that my mother tongue is not English, so I actually think about this issues ;) ) so I decided to leave it simple for now, just showing a short message asking the user to edit this page.

Making wiki editing easier

So let's imagine that after these changes the user likes the wiki enough to go ahead and edits the page. Here is the screen provided to edit the page:



An empty textarea with no clue about the syntax to use. Even those that know what a wiki is and know some wiki syntax conventions are quite puzzled by this. When I first used it, I tried some conventions from MediaWiki and Zwiki (the two wikis I had used most) and only some of them worked, I tried again, and then again, and then... I become so frustrated that I didn't want to use the wiki again. Since then, Ray has done quite some improvements to the wiki syntax support, but unfortunately they have passed mostly unnoticed.

The solution is simple, just add some brief wiki help when editing the page with the most used conventions and a link to more detailed documentation (that opens in a new page, of course). Here is the result:



Now, some people won't ever want to use a weird syntax to input their contents. Fortunately Liferay also supports Rich (HTML) editing using an integrated editor (FCKEditor by default). I don't want to go over if that's better or worse becase often that discussion seems to me similar to discussing which is better Coke or Pepsi. I think both options have pros and cons and it's just up to the taste of each person.

But, until now choosing the HTML option had a very nasty side effect: you loose the ability to create pages. Since pages could only be created by writing a WikiLink (using Camel Case) and then clicking the link, when you choose HTML the link is not automatically generated and there is no way to create pages. This was very easy to fix. I just added a new action that allows creating a new page. When selected it shows a JavaScript prompt box asking for the name of the new page informing that it must follow the CamelCase wiki conventions:



After introducing the name the user is taken directly to the edition of the new page just as it happens in most wikis.

After these changes we have a wiki that behaves as people would expect, it's possible to show wiki pages, edit them, create new ones, link them. Now this is starting to look like a real wiki.

Leveraging the underlying power

So far we've only covered very basic features, but Liferay's wiki has some very nice advanced features such as as page history, page links, recent changes, orphan pages, permissions, ...

The feeling that I had about all these features previously were that they were in the way and didn't let me do what I really wanted to. But once you are able to do the basic tasks, the most advanced features start to be of interest. As I described in the previous section, I've aggregated all of these options in the 'Actions' menu:



But the feature that I'm most interested in explaining is the administration of nodes. That's exactly what used to be the first thing that was presented to the user after all these usability changes, and it hasn't been removed. It can be accessed by clicking the "Administer Nodes" option of the actions menu.

So, we come back to the question of what are nodes? Nodes are actually separated sets of pages. Some wikis call it spaces, namespaces, etc. In Liferay they are called nodes. I thought about changing the name, but decided that it wasn't that important for now.

One of the problems with Liferay's nodes is that its presentation does not reflect what they are. To fix that I used one of the most powerful UI widgets (if used the right way): tabs. Tabs are a perfect fit here, since they do the exact same job as tabs in real life physical folders in which each tab contains a group of sheets of paper. So I added tabs in the top part of the portlet and made them be available always. One important thing of tabs in UI design is that they have to work as people expect to be effective. That means that the tab representing the current node should always be selected when the user navigates through the pages of the node, or even when any of the options in the 'actions' menu is used. The only screen in which the tabs are not shown is in the administer nodes screen. Here are a couple of screenshots that show the administration and the end result:





Final touches

After all these changes I was already pretty excited, because the wiki was looking much better and the advanced functionality, specially nodes, was very cool. Yes, believe it or not, I was aware of all this functionality because I knew the code, but seeing it in use and presented this way made a different impression on me.

Some final touches to the portlet that I made were:

• Friendly URLs: most wikis products have friendly URLs and Liferay has a pretty cool framework to implement them for portlets. So I used it and in about 10 minutes the wiki had friendly URLs
• Most wikis have menus or even boxes with different type of content around. Leveraging portlets Liferay is unbeatable here but to leverage that it was important to maintain the portlet in NORMAL state while the user was navigating it. I reviewed all links to make sure this was the case and changed those were it wasn't.
• Configurability. I created two new properties in portal.properties to allow configuring:
  • The name of the default node that is automatically created
  • The URL that is used to build the link for more help on wiki syntax. By default it points to an article in LiferayPedia, but I'm pretty sure many people (specially in non-english speaking communities) would want to substitute that with their own customized help

Conclusions and availability

The main conclusion from this work is that usability does not only determine if a certain tool is easier to use or not, often it determines if the tool or a some of its features are used at all or not. That's something very important for us software developers because, what's the point of implementing a feature if it's not going to be used?

Disclaimer: I'm not a usability expert and just made some very informal usability tests when developing this, so I'm pretty sure there are still many usability flaws. I just hope that it's a good start point.

The second conclusion is that our wiki is much better than we thought. It still lacks important features but it's a very good foundation. In fact I have a huge list of improvements that I'd like us to implement. Anybody in the audience would like to sponsor some of them so that we can spend more time on them? :)

Finally some of you have asked when this will be available and how you can test it. The answer is that it's already available in Liferay's subversion repository and will be included in the 4.4 release (no release date yet). If you can't wait to try it out download the sources from sourceforge, build them and run tomcat (or your app server of choice).

Ok, that was a quite lengthy post, I'll need a few days of vacation from blogging to recover ;). I hope it was helpful for all of you interested in the subject,