Lessons Learned from Establishing an Internal Knowledge Base, Part II

In the previous post, I talked about Agolo’s search for a system to use as our internal knowledge base. We settled on DokuWiki in the end.

In this post, I’ll talk about the challenges and issues we faced after choosing to proceed with DokuWiki.


Installing DokuWiki was more challenging than expected. My teammate, Tom, did all of the installation and server setup work. Even though we used Bitnami to manage the installation, we still had some ramping up to do when configuring the server. None of us is intimately familiar with the LAMP stack (minus the M, in this case). So, we faced some challenges right away. We were okay with this because it’s just a one-time issue. Eventually, we overcame these issues and installed the wiki on an Azure virtual machine.


We had to install a number of plugins to truly make the wiki useful. We knew this had to be done, and the plugins are one of the main reasons we chose Dokuwiki in the first place.

The challenge then became picking which plugins we should install. I spent some time browsing the list of the most popular plugins here.

These are the most useful plugins we’ve seen so far:

I consider these plugins to be absolutely essential to take full advantage of DokuWiki. Being able to paste images directly into the WYSIWYG editor and being able to list all pages under a namespace are essential. We have an “Add new page” widget on the wiki’s landing page, as well as an Indexmenu of the root namespace that allows us to see the high-level pages and namespaces.

However, we are careful not to install too many plugins. The more plugins we install, the more we run the risk of plugins negatively affecting each other. Also, if a plugin becomes deprecated, it just causes maintenance hassles when it comes time to update the wiki software.


We do a nightly backup to a GitHub repo. It’s a simple shell script run as a cron job. All it does is a git add, commit, and push to a private repository on GitHub. Git is smart enough to only create a new commit when there are changes, so our private repo’s commit history stays relatively clean.

I’ve set it up so only our text and images get backed up. However, it should be possible to backup the entire DokuWiki directory from your virtual machine.

Markdown vs. Wiki Syntax

Almost all of my teammates are familiar with GitHub-flavored Markdown. Unfortunately, DokuWiki only supports Wiki syntax out of the box. These two markup languages are similar enough that it caused our users a lot of confusion and an unnecessarily steep learning curve.

The Markdowku plugin helps to reduce this friction, but it also causes some other issues. The WYSIWYG editor becomes unreliable — bulleted lists and bold vs. italics have conflicting markup in Markdown and Wiki Syntax.

The editor is already difficult to use in the first place (no live preview, and no undo after you click one of the buttons, for example). This conflict further complicates the matter and frustrates users.


Wiki software’s UX feels outdated by at least a decade in 2016. So, it is absolutely imperative to install the Bootstrap3 template. Not only does it make the wiki look and feel much more modern, it also allows you to install themes from Bootswatch. This goes a long way in making users feel welcome when they use the wiki. Without a well-designed, modern, clean theme, users are immediately turned off and are less likely to look at the wiki.

This brings me to my final and most important point.

 Expectation Management and Learning Curve

Some intangibles became apparent once we installed the wiki. The most important takeaway is users are naturally disinclined to start using a new tool when they are already acquainted with an old one.

In this case, we had already been using a hodge-podge of Dropbox, Google Drive, Slack, and Evernote. We had sort of found a kludgy system that worked for us in most cases. It just wasn’t scalable, so I advocated strongly for wiki. While we got buy-in from everyone, it is simply difficult to get everyone to enthusiastically and consistently use the wiki. It takes time to use it to its full extent.

If the user has never used a wiki before, it can be intimidating, frustrating, and boring to learn all at the same time. It would feel like a waste of time to them when they could just create a Google Doc and Slack the link to someone.

I was excited when we first launched our wiki. Over the next couple of weeks, I saw that my coworkers weren’t using the wiki to its fullest potential. While they had a positive attitude toward it, they are not as excited as I was. I had to do some introspection to find out why I thought the wiki is an essential tool, and why my coworkers aren’t as enthusiastic. I came up with the following reasons.

First, I hadn’t taken the Network Effect into account. At my previous company, I quickly learned to use the internal wiki because it was actively read and contributed to. When everyone is already using the wiki on a daily basis to accomplish almost every non-trivial task, a new user is more likely to spend the time to learn it as well. The learning curve is not a huge deterrent because the rewards are tangible and obvious. However, because we are all ramping up on the wiki at the same time, each of us doesn’t see the full benefits from everyone else’s wiki usage yet. We are not yet reinforcing each other’s use of this important tool.

Secondly, I was involved in the research and installation of the company wiki, so I had some idea about DokuWiki’s internal workings. So, a concept like namespaces seemed natural to me. However, to a general user, the idea that a namespace can sometimes be a page but not always is quite confusing. In addition, page creation involves much more brainpower and typing when you make use of namespaces. This is in stark contrast with something like Evernote, where page creation is 1-click and doesn’t require the user to think of a hierarchy of namespaces. This is an instance of having to unlearn UX design patterns that have emerged in the last decade since wiki software was dominant.

Most importantly, Wiki has a relatively steep learning curve. This is especially true in 2016 when the wiki paradigm has so many competitors that have leapfrogged over it in terms of UX and ease-of-use. When a user tries to use a wiki software, they have to unlearn a decade’s worth of UX design patterns.

It takes a while for users to grok the idea of an interconnected web of documents as the model for a knowledge base. It’s much easier to think of it as a set of files inside folders (like Evernote, Google Drive, and Dropbox). If that’s what the user is expecting, then they will see wiki as a very poor substitute for the more modern cloud storage services. So, it becomes important to coach them and mold their thinking to see the advantages of a highly-scalable web of plaintext with an auto-generated table of contents, tagging, and easy hyperlinking.

If you are in charge of installing an internal knowledge base at your organization, make sure you invest time in coaching. Write some easy-to-understand introductory wiki pages, fill it with screenshots, and encourage everyone to read them. Create a sandbox page and a namespace for each of the existing users. Schedule 30 minutes for everyone to sit down and play with the editor and learn the syntax. Do your best to make the learning curve shallow. Do not underestimate the effects of a well-designed, modern theme and a helpful set of plugins. Make the experience as welcoming as possible for the users.