Liferay's wiki and why usability is so important

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 ;)


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 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,

Thanks for these improvements! I look forward to testing as soon as I get a chance.

Superb write up. For someone that claims to not be a UI expert, you sure play one well on Liferay. I can't find much in my notes on this that you haven't already covered. You have captured 95% of what makes any wiki work well, and made it nicely consistent with the Liferay GUI. Really well done. Having said that, I will toss in a few pennies:

1) You make no mention of templating and CSS, and I think you may already be making a mistake that most wikis do, treating the presentation layer as an afterthought (but i could be wrong). Unless you're just speaking of the default look and feel, you seem to be assuming that one particular interface is always the right solution in a wiki, so you fuss over size and position of title, etc. Most wikis have a monolithic approach to the Wiki, and that ALWAYS limits how the wiki can be used. For example, in a wiki URL directory, or personal profile, or product record, you may want a somewhat different overall look. You should just build the core structure, and rely on templates/CSS, and let the portlet designer design on the final presentation. Properly rendered, even your tab controls could be made vertical side tabs via CSS. (You probably do intend this flexibility. You've thought of everything else emoticon

2) I would prefer that Liferay Wiki not reinvent wiki syntax, when both TextTile and Markdown are so widely used and have parsers out there as Open source. They have a lot of work in them, and as you later support footnotes, annotations, etc., those parsers become a lot of work you can avoid (but the existing parses can be customized.)
(Mediawiki is a homegrown, and rather inferior, IMHO)

3) Your help text sidebar is good, and ones like it have become common on many wikis, but it must hide, and that state persist, or it annoys the hell out of power users who don't need it. Any our users always complain about that plain dumb, scrolling sidebar, or worse, separate page. Consider an accordion bar (sliding vertical panes), with panels like " Text, Lists, Links, Tables,". This will instantly distinguish Liferay wiki from 99% of them out there, where help is an afterthought.

4) Are you considering your wiki as the repository for localization texts? That was a great idea in Mediawiki, but not particularly well implemented (at least, 3 years ago when I used it most).

I am going to get my partners to run this today, so I can actually use it. Kudos!
Jorge, this is awesome! I've been meaning to grab the latest source for days now, and you just provided the motivation. :-)

You totally rock. I will check it out and tell you what I think.
Hey All,

Thanks a lot for your encouragement, you made my day emoticon

@Matte: You are right, I was careful enough to allow CSS styling. In fact saying that I made the title bigger was an over simplification. Here is an example HTML code that I'm pretty sure will keep you happy:

<h2 class="wiki-page-title"><a href="...">FrontPage</a></h2>

Regarding the wiki syntax, I've been taking a look at TextTile and I'm sold emoticon It's absolutely great. Ideally we should be able to support as many engines as we want if they have a Java engine. BTW, I've seen that there are several Java libraries for Textile, do you recommend any of them in particular?
Regarding hiding the help, it's a good idea and simple to implement (added to my TODO list). Finally, regarding the repository for localization texts, could you elaborate on that? I would suggest doing it in a separate forum thread and linking it from a comment here.
hot i just dugg your article =)
(cross-posting this notice on related topics / blogs / forums)

Per several comments (@Matte's on original Blog post and Jorge's in the Forums):

I have started a Proposed Project page at Liferaypedia to try to capture key discussion points and bring together information in Blogs / comments / forums.


I am shamelessly refactoring some of this content, and hope this is not a problem with anyone - trying to give credit and make references as best I can given time available.

Greate that you are improving the wiki portlet. I haven't used it before but now were are implementing it for a user and see the same things that you are talking about.
The main issiu that we have is the creation of pages and the linking betwean the pages. In the classic view it's very easy en intuitive te make new pages with Camel Case notation. But having a webpage/wiki page without images and rich content is like prehistoric.
So we want to use the html view but then we loos the cool Camel case page creation and linking.

I see in your post that you made a way to create pages but the screenshot show that you create it outside the editor. How is it then possible to make links to these pages from other pages?

I would like to try this but I don't have any knowledge how to do so. I think that it's not possible to just take the wiki portlet files.

But greate initiative. It really needed/needs some changes.
Whow! Great improvements. I was in the process of looking for an alternative to Liferay's wiki, but I don't think I'll need to now.