Comparison of Git-powered wiki features in cloud-based SCM tools

Comparison of Git-powered wiki features in cloud-based SCM tools

A while back we compared the issue tracking features of four major SCM tools. Since people were quite interested in the comparison, we decided to continue the series with a similar post about the Git-powered wiki features. After all, an effective and reliable documentation is a must have for any software development team.

If you do not want to read the detailed breakdown of the wiki features and their characteristics, you can jump straight to the summary table.

What's a Git-powered wiki?

Let's get the definitions straight before we dive into the comparison. A git-powered wiki is a wiki that stores its contents and change history in a git repository. "Errare humanum est" so every now and then somebody adds or removes wrong stuff in the wiki. Thus the change history is a good thing to have because it allows you to restore earlier versions of the documents. Additionally, storing wiki contents in git repository allows you to clone the repository locally and edit the content with your preferred text editor, and integrate tools that auto-generate documentation from code to the repository.

Now that we are on the same page, let's move on to the actual comparison!

Deveo

First, we need to clarify that unlike GitLab and GitHub, Deveo allows the user to create multiple repositories in one project. BitBucket allows multiple repositories per project as well but the wiki's are repository-bound in BitBucket. In Deveo the wiki is project-bound. The other tools restrict the amount of repositories per project to one. This, of course, affects the project bound documentation a bit. E.g., in Deveo, you'll find the wiki's git repository's cloning link from the repository view, and not from the wiki view.

Documentation in Deveo differs from the other SCM tools in some distinctive ways. The first thing you'll notice is the side-by-side view in Deveo's wiki editor. This handy feature makes the editor easy to use, especially if you are not a seasoned Markdown expert. If you have only a little experience in Markdown and try to create e.g. tables for the first time, I can tell you that the side-by-side view will save you from a lot of mental pain!

The side-by-side view is also useful because Deveo lacks the function bar buttons that the other tools have. However, you can consult the Markdown syntax easily through the link below the editor if you don't remember the syntax by heart.

As I mentioned earlier, you can access the wiki's git repository through the repository view. Here you'll also be able of cloning the wiki git repository.

In the repository view, you can also access the version history on the code level.

Since all of the reviewed tools store the wiki content to a git repository, attaching large binary files in them may not be a good idea in the long run. Deveo has solved this by supporting also WebDAV repositories. You cannot manage the WebDAV repository from Deveo's wiki but you can link the file from WebDAV to the wiki page. Bear in mind, though, that WebDAV doesn't version the documents stored in it so you probably want to handle versioning by naming conventions.

Summary of Deveo

Deveo's wiki is easy to use and gets the job done. Missing function bar buttons is a small disadvantage but the parallel view is an awesome addition and covers for the missing buttons. Search function for the wiki pages is a valuable feature.

GitLab

GitLab's wiki editor resembles GitHub and BitBucket quite a lot. It is intuitive to use and the function bar buttons make the formatting simple. In addition to this, a remarkable difference to Deveo is that you'll find the cloning link in the wiki from a top navigation bar under "Git Access".

GitLab has invested in the layout and graphical assets. Gitlab Flavored Markdown (GFM) allows users to make some additional formatting like emojis.

In addition to Markdown, GitLab also supports RDoc and AsciiDoc documentation generators

Summary of GitLab

Visual layout and the extended Markdown syntax makes GitLab's wiki editor nice to use. Support for documentation generators Rdoc and AsciiDoc is a plus. GitLab's top bar navigation has its supporters but personally I prefer left-hand navigation. Thus, I needed to change my mindset in order to find the right sub-pages. It took me a while to find, e.g., the cloning link.

GitHub

I found GitHub's navigation more intuitive than the navigation in GitLab. Maybe it is the pages sidebar that lists all of the wiki pages you have created for your current project that makes the difference. There is also a customisable sidebar and footer, which remains the same on every wiki page. This allows you to add, e.g. guidelines for your wiki or make your own navigation paths.

In Github, the cloning link is visible on every wiki page. In my opinion, this is a good thing to have, because now you'll always find the link in a blink of an eye. In other tools you need click a link or find the right repository in order to find the cloning link.

A noteworthy detail in GitHub is its support for multiple syntaxes and document generators. In addition to Markdown, RDoc and AsciiDoc, which were supported also in GitLab, GitHub supports Creole, MediaWiki, Org-mode, Plain Old Documentation (Pod) for you Perl programmers, Textile, and reStructuredText.

I did encounter quite a big disadvantage with GitHub wiki: you can only add images by adding an image link. Unlike in other wiki editors, you cannot just upload a picture to the editor; in GitHub, you need to add an image URL. For other types of attachment, there isn't even a dedicated link or button for adding attachments. Basically, this leaves you with two options: either you upload your files to another website and link them to your GitHub project, or you clone the repo, add the attachments, and commit them. Both of these feel a tad too complex when the other tools let you just drag and drop files.

Summary of GitHub

It is easy to navigate in GitHub's wiki tool and using the editor is simple. You can choose from multiple different markup languages but at the end of the day, you usually need just one. Complexity in adding attachments is a big minus.

BitBucket

I need to admit that at first, I was a bit lost with BitBucket. Since I'm not that used to using it, it took me a while to understand that you need to enable the wiki feature in the repository settings. After enabling it, you are ready to create documentation for your repository.

The editor is similar to GitLab and GitHub. Nothing too fancy or complex there. Cloning link is easy to find from the top right corner and it is visible on every wiki page. History can be found easily and you can also check the lines of code by clicking the SHAs in the history view.

An interesting feature in BitBucket is that if you create a Mercurial repository, the repository-bound wiki is naturally stored in a Mercurial repository as well.. This results apparently from the fact that wikis in BitBucket are repository bound, although one project may include multiple repositories.

What comes to text formats, BitBucket supports Markdown, Creole, reStructuredText, and Textile.

Bitbucket has a nice parent-child folder type of approach to navigation. In order to find all of the pages, you'll need to click the parent folder, which in this case is the repository name in the Wiki view. Then you'll be able to find a list of the wiki pages in alphabetical order. If you happen to have tons of documents, a search option would have been nice to have.

You'll also face some complexity if you want to attach files other than images to your BitBucket wiki. You can just drag and drop image files but there's no simple "Attachments" button or a link for any other type of attachment. Similarly to GitHub, your options are 1) to upload them to an external webpage and link to it, or 2) to clone the repo, add attachments, and commit them.

Summary of BitBucket

I find it counter-intuitive to separately enable wiki from the repository settings. On the other hand, if you do not want to have a wiki in your project, this is a good feature. Furthermore, adding attachments should be easier, and a search function for the wiki pages would improve the user experience remarkably.

Conclusion

All of the reviewed git-powered wikis have a lot of similarities, such as intuitive editors and nice UIs. However, differences do exist. Since everybody values different features, I listed the key functionalities in the table below to help you find out the differences more easily.

Please share your thoughts on social media and tell us, what functionalities you appreciate most in a wiki tool.

Want to learn more about why Deveo is the no. 1 alternative to GitLab, Github, or BitBucket? Check out these sites:

Seamless software development.

Code management and collaboration platform with Git, Subversion, and Mercurial.

Sign up for free
comments powered by Disqus