Improve our wiki portlet or integrate an existing wiki... which is better?

Jorge Ferrer

October 29, 2007

3 Minute Read

It's no big secret that Liferay's bundled wiki is one of the most often criticized. And I can understand it. For example, when you first add the portlet you get a view that looks nothing like a wiki and the only option available is adding a node:

Screenshot of the wiki portlet when it's first used

Hmmm... but what is a node? You may ask. If you go ahead and create a node, it doesn't improve a whole lot:

After creating one node

Nodes are actually a very cool feature of Liferay's wiki, but presenting it up front scares people because it makes the tool very different to typical wikis and requires investigation and effort to get it working. This is just an example of the usability problems that the portlet has but it also lacks some features often found in the most popular wikis such as MediaWiki, JSPWiki, Confluence, etc.

Because of this, the wiki portlet is often the target of criticism and people asks as to do something about it, but ... is it better to spend the time and resources in improving our wiki or is it better to integrate one of the popular wiki tools out there?

This is a question that comes up often in internal conversations among Liferay's developers, in blogs from first time users of Liferay and in the forums. So I thought it was time to analyze the advantages and drawbacks of each approach:

Integrating an existing Wiki
The requirements would be: open source and with a good community, actively developed and support for all modern features of wikis.

Advantages

Time, time, time. Unfortunately time is finite and we never have time to do everything that we would want to do, including making Liferay's wiki the best wiki ever. This option frees time since other people are developing the wiki that Liferay's users will use. That way Liferay's developers can concentrate on making the portal-specific features the best ever ;)
Specialized knowledge: the people developing the wiki will most probably know more about wikis than Liferay's developers.
Advanced features: an specialized wiki product will always have more advanced features, as a result of the previous two points.
Some Liferay users may already be familiar with a wiki product and would like to use it within Liferay

Drawbacks

Lack of a unique support source: when an external tool is integrated, people using Liferay have to go to two different sources to get help to solve any problem they may have. And that includes both professional support and community support.
A unique set of pages for the whole portal. Liferay has a feature called data scoping what allows each community (and organization and user) to have it's own data. For example if you put the Message Boards (or Calendar or Wiki, or ...) portlet in community A and also in community B, each get their own instance of the tool, with separate categories, threads, etc. If, for example, JSPwiki is integrated, there would only be ONE set of wiki pages for the whole portal as opposed to one per community.
Separate user repositories. Each wiki product that I know has their own user management system which has its own repositories of users. Fortunately, sometimes it's possible to solve this but having Liferay and the wiki to use CAS, LDAP and/or a some custom integration. Although that means more work to get the portal running.
Lack of integration with Liferay's permission system
The wiki's internal navigation and menus sometimes conflict with the portal's navigation, causing confusion to the end user.

Improving Liferay's bundled wiki
The benefits and drawbacks of this option are the exact opposite of those already mentioned for the previous option. But I'd like to highlight some of them:

Benefits

Separate sets of pages per community. Furthermore, each community can have several nodes (aka spaces) to separate their own pages in different groups.
Full integration with the permission system. It's possible to set different permissions for different pages and create roles that give specific permissions for the wiki portlet.
Integration with the new asset publishing system. This makes it very easy to generate lists of pages such as: all pages ordered alphabetically, latest pages created, latest pages modified, etc.
Integration with some other of Liferay's transversal features: comments system, tagging, rating (to be done), etc.
A single place to ask for support (either profesional support or community support)

Drawbacks

Some people are already disappointed with it and may not want to give it a second opportunity (I hope to be wrong here)
Lack of advanced features
The wiki needs some urgent usability improvements. Without it people won't see it as a good base to build on top of.

Conclusions
The more I think about it and discuss about it with other people, the more convinced I am that we should do both. Why? Because both options have advantages that the other will never have. What about the time? Yeah, that's the problem, time is finite, BUT:

Our wiki is actually not that bad and with some usability changes that should not take more than a day it would be a whole lot better (and I'm cheating about the estimate here, since I've already done it, more on that on a later post)
Liferay is a good platform for integrating existing applications and we want to improve our support since it's an strategic feature of a portal. In fact, just try to download the JSPwiki WAR and copy it to the autodeploy directory, you'll be surprised to see that it's been automatically integrated as a portlet. Of course the integration is not complete, primarily because the user repositories are different, but it's a very good start point.
Since we are considering integrating an open source product we can get the communities of both products to collaborate. That way with enough time several of the above listed drawbacks could be eliminated.

Thoughts?

19 Comments

Please sign in to comment.

Jorge,

Excellet write-up! While I was initially inclined to say "do both, and start with the external," after reading your points, I have changed my view. While there are tradeoffs, I say stay with the internal Liferay idea.

There are many things a wiki can be used for, especially documentation, that should more than help Bryan feel good about the time spent. This using Mediawiki now-- which really isn't as good as it's ubiquity suggests -- always seemed weird to me. If you were using your own wiki, you'd be compelled to improve it--even only in baby steps, and it would already be more usable by now.

As you have articulated it, the data-scoping, asset management, permissions, and all the other benefits of the internal option make it a no-brainer (for me). Those are precisely the things that ALL other wikis lack, and it makes them suck such major chunks. All wikis start simple, and in the end, everyone realizes that there's no free lunch. In the end, you need the power of something not quite as simple as you envisioned. In my view, having looked at many of them, and tried to adapt many to real world publishing needs, a Wiki is no longer just a simple way for coders to crank out instant web pages without a lot of markup. Rather, they're full-fledged, collaborative publishing systems with all of the core issues found in most CMSes. Thus, it makes far more sense to have all the architectural robustness promised by the internal Liferay wiki from the outset, rather than trying to retrofit an alien being into the native environment.

Again, I am a mere user and GUI designer, and not an engineer, but I would think you could simply get started with a very simple portlet prototype that starts from a standard wiki "main view" that adopts the same tabbed approach that JSPwiki uses. (I've seen many, and theirs is actually quite rational and familiar, right down to the idea of a "More" tab to the far-right of the standard options). Just having this basic view will immediately break you out of the existing, and somewhat hostile "nodal" view, and get people oriented to a more familiar UI paradigm. Then we can all discussing adding features to that frame, starting with History, which is always vital.

From what I understand, there are many Textile parsers, and there must be one in Java, no?

From what you've said, it sounds like you may already have a prototype of this. If so, I'd love to see it (privately, if you choose), and we could discuss it further.

I think the impact that a good wiki tool will have on Liferay documentation alone, makes it a worthy, immediate priority. I will certainly help in any way useful to the effort.

Please sign in to reply.

When i enter a blog post thread. it would be very helpful if you could embed the post title in the browser title tag. Some of us still bookmark, rather that RSS, and it makes filing active threads much easier to mark.

You can truncate after 40 chars, to keep it brief
Example:
"Liferay:Jorge Ferrer :: Improve our wiki portlet or integrate ..."

Please sign in to reply.

Yes, I've already made the usability changes that I suggested. In fact I've just committed them to our subversion repository a few minutes ago. You can read more about them in http://support.liferay.com/browse/LEP-4111

Also, I'll try to write another blog entry with more details and screenshots.

Please sign in to reply.

I'll be checking out those changes also.

Please sign in to reply.

I am excited to see this discussion moving forward.

Just to share what I've ended up doing with Liferay, and how that ties into wiki needs: (and pardon any rambling in advance, I have lots of thoughts to get out!)

We have 3 small businesses all sharing somewhat similar ownership and resources with about 40 employees total. There is a lot of optimism right now that Liferay might provide the "holy grail" of collaboration and work environment across all business units and employees by providing a "one-stop-shopping" for employees to do daily work. (I should note our employee base is definitely not high in the computer skills dept. - we sell pipe and fittings mainly)

As you've mentioned the data-scoping and granular security that Liferay offers is what makes it such an outstanding fit to our particular organizational set-up. As administrator, I routinely get told "We just hired new worker bee B, and this worker bee should be able to: access everything but accounting documents in company 1, only be able to view vendor catalogs and work process documents in company 2, and have nothing at all to do in company 3". Any Liferay does all this with ease + a little creativity in my community set ups.

So, having the wiki follow with same functionality would be great. And the existing Wiki does indeed do all this.

But, back to my real-life implementation - I have tried over and over to make use of Liferay's Friki Wiki to host the very content we want in the wiki - standard office procedures, purchasing instructions, etc. - and despite my best efforts, the results I get are visually unappealing at best, or completely unusable at worst - despite a tremendous amount of work trying.

Enter JSPWiki - I have deployed it using the autodeploy feature, and no joke - 20 minutes later I have several of our standard procedures published and in a condition to roll out for use. No, I am not integrated with the user-level security and permissions.

Another day of work, though and I have implemented more-or-less data scoping (outside of liferay) by simply defining multiple wiki's - so now I have wiki_company1, wiki_company2, and wiki_company3.

Instead of deploying through portlet, I make URL pages within each community that open the appropriate wiki (i.e, http://192.168.1.1:8080/wiki_company1).

Now, it's not secure by any means, as anyone could figure out how to jump wiki's if they really wanted to - but the point is multiple unique wikis should not present much of a problem.

JSPWiki does store in flat files by default, although I understand it can be configured to work with database. Also, from reading the JSPWiki.properties file, it does appear that it could possibly tie into Liferay's authentication scheme (have not had time to look deeper into this).

Also, notice JSPWiki has been accepted into Apache Incubator - which I view as a good sign of ongoing development and improvement - vs. Friki which seems to be languishing. (not picking on Friki, just trying to "hitch my wagon to a strong horse")

I am not "active" in JSPWiki community, per se - but will post some links on their mailing list back to this blog and the forums to try to promote some cross-pollination between the developer communities.

To me the existing feature base of JSPWiki has all sorts of benefits that would take quite some time to implement in existing Friki: For example: Sortable tables ( http://www.jspwiki.org/wiki/BrushedTemplateSortableTables ) Accordian sections ( http://www.jspwiki.org/wiki/BrushedTemplateAccordion ) and a lot more - all ready to go - but yet does not seem to be overly complicated for novices to understand. A lot of feature functionality in a simple package.

Finally, I certainly will be happy with whatever direction the wiki takes, and am just hoping for anything better than the current.

Please sign in to reply.

I cross-posted some links from this discussion to the JSPWiki mailing list, and got this reply from Janne Jalkanen - the lead developer / originator / not certain his official title of the JSPWiki project. Because he is currently unregistered at Liferay, he could not post directly:

<begin Quote>

Re: [Jspwiki-users] More on Liferay integration
(Janne Jalkanen, Mon Oct 29 14:48:08 2007)

Couldn't figure out how to post to either blog or the forum, so I'm
responding here :-)

I noticed a couple of worries. First of all: authentication.
JSPWiki supports the JAAS authentication scheme out-of-the-box, so
you can use whatever you have built-in already. In addition, our
authentication system is fully pluggable, so you can just write a
plugin to your own code.

The other worry mentioned was that there would be one global
namespace for all users. This is true for the stock jspwiki
installation (we're working on it!), but if you are embedding, you
have several choices ranging from using JSPWiki just as a rendering
engine (and providing the page repository by yourself - might be good
if you already have a storage system) to spawning a new WikiEngine
instance for each of your user areas. So embedders do have a bit
more freedom than people who just install it.

Anyway, practically all of the internal modules can be overridden via
configuration, so you do have quite a lot of flexibility in figuring
out just the right level of integration to your app!

/Janne

Please sign in to reply.

First of all thanks for sending this to the JSPWiki mailing list and for posting the response back. Also thanks to Janne (in case he reads this) for his answer.

I think that the idea of using the JSPWiki engine directly is very attractive. Specially since, as has been mentioned, the friki engine is not being maintained so actively. Do you know of any links that provide more documentation about how to make it work? Or better, does anyone reading this, want to give it a try? I would be glad to integrate any changes back into Liferay.

Please sign in to reply.

Jorge,

1) The comment module is still not a forum. Might you consider migrating this discussion to the forums? Better still, could you get Liferay OK to start a "liferay future development only" forum, so as to not crowd the current user forum. I realize multiple forums were a problem in the past, but two forums is not 6 emoticon

2) Having been down this road before, where something already built was really seductive, I am wary of jumping on JSPwiki too fast. Sure, it's there now, but how much of what is really there, would be that hard in Liferay? Probably nothing too critical, given that you already have the scoping and permissions that they do not. Of course, you know better, but if you are really attracted to the external approach, I would make the scoping a priority from the get go. If you don't add it first, you probably never will. And as Vaghan's post attests, I think thats' the single greatest strength of the liferay wiki. It will instantly put it in a league that I have only once seen in a big, overblown, overpriced proprietary wiki. And you may find not much else is really required to have a potent, highly useful and marketable module that pulls in a lot of new Liferay users.

I will check out the changes as soon as I can. Do you suppose you could put up a working prototype we might interact with?

Please sign in to reply.

Hey Jorge is your wiki changes gonna make it into 4.3.x?

Please sign in to reply.

I think it would be a good idea swapping out the wiki engine. Ideally you would make that configurable, but I'm not sure how hard that is. My biggest concern with Friki is that it isn't in active development anymore.

Please sign in to reply.

Jorge,

I looked over your enhancements. And they certainly are what it needs, but if, as Michael says, the entire project is not in active development, none of those seem trivial to implement.

On the other hand, what's really required to add the data-scoping, or something else that meets Vaughn's needs. If that's not a big deal to add by the Liferay team that understands it best, the rest of the wiki UI stuff would probably not be hard for others to jump on, given the lure of a very unique security capability. I would not sneeze at that potential. Wikis are becoming big tools, and the security blows chunks on 99.9% of them.

If just having "any old wiki" is the goal, I suppose the JSPwiki is the only choice. But I suspect it will never become the integrated, powerful tool you envision, and really think there is a real industry demand for that.

My $.02

Please sign in to reply.

I've made a new post explaining the improvements made with more detail:
http://www.liferay.com/web/jferrer/1/blogs/liferay_s_wiki_and_why_usability_is_so_important

@Dave: I don't think this will be available in 4.3.x. Although bchan has the last word on that

@Matte: when I mentioned using JSPWiki in my comment, I was referring to using its engine for our internal wiki, since Janne suggested that was possible. That would make no difference to the end user but could make adding certain features a lot easier. I still think that we should support both, improving our wiki and integration of external wiki products.

Please sign in to reply.

Wiki syntax discussion on JSPwiki

This discussion on JSPwiki ...

http://jspwiki.org/wiki/IdeaAdoptMediawikiFormat

...is an excellent way to get up to speed on the "Wikisyntax" arguments raging lately. The first, main article is actually viciously attacked in the comments which follow it, but the entire thread is worth reading from end to end.

All in all, I like the attitude at JSPwiki, and am coming to like that idea a lot, given that you clarified what you meant to do with it. I am still not clear on whether your current work would front end that engine or not. I am assuming it would.

Next week, we're going to bring up our own version and play with it, probably applying our emerging tag manager as a test.

Please sign in to reply.

Per several comments (@Matte's on this page 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.

See http://wiki.liferay.com/index.php/Wiki_Overhaul

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.

Will work more on it as time available.

Please sign in to reply.

Vaghan,

Excellent idea, althought I tend to hate commenting in wikis, as it's just such an awkward format for discussion. Before it gets out of hand, perhaps you could create 2 or 3 discussion pages, and bump them right up to the top, so the core arguments don't muddy up the primary article? This appeals to me, but perhaps it's wrong. Your page. Your decision.

Please sign in to reply.

@Matte you may be happy to know that threaded blog comments are back in trunk emoticon

Brian and I did some test until we find a solution that keeps the simplicity of a chronological comments lists but keeps information of the parents (and offers a link to them)

Please sign in to reply.

Jorge,
Great article and welcome enhancements to the wiki. We look forward to testing the new version. As new Liferay users, is there a good overview of wiki features and how-to other than what's in the documentation? I couldn't find much, such as administering pages (adding/deleting) or examples of the Liferay wiki in action.
Thanks

Please sign in to reply.

Hi Ron,

There isn't much user level documentation right now. We are working on it but meanwhile feel free to ask in the message boards any question you have. The community is usually very responsive.

Please sign in to reply.

Interesting to see that they've now also included MediaWiki!
However I'd really like to see a business user friendly wiki with WYSIWYG editor such as MoinMoin!

Please sign in to reply.

Related Assets...

No Results Found

More Blog Entries...

Ben Turner

October 21, 2025

Feedback

Blogs

Improve our wiki portlet or integrate an existing wiki... which is better?

Jorge Ferrer

Related Assets...

More Blog Entries...

New Blogs UX

Liferay Objects FreeMarker Display Widget

From Theme to Theme-less: The Smart Path to Faster, Future-Ready Liferay DXP Upgrades