How to Choose the Right Git-Powered Wiki for Your Team
Git-Powered Wiki Comparison: Helix TeamHub, GitLab, GitHub, and BitBucket
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 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 Is 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 mistakenly adds or removes things 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 a Git repository allows you to clone the repository locally, 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!
First, we need to clarify that unlike GitLab and GitHub, Helix TeamHub allows users to create multiple repositories in one project. BitBucket allows multiple repositories per project as well, but wikis are repository-bound in BitBucket. In Helix TeamHub, the wiki is project-bound. Other tools limit the number of repositories per project to one. This, of course, affects project-bound documentation. E.g., in Helix TeamHub, you'll find the wiki's Git repository cloning link in the repository view, not the wiki view.
Documentation in Helix TeamHub differentiates itself from other SCM tools with a few distinctive features. The first thing you'll notice is the side-by-side view in Helix TeamHub's wiki editor. This handy feature makes the editor easy to use, especially if you are not a seasoned Markdown expert. Side-by-side views will save inexperienced Markdown users a lot of frustration.
The side-by-side view is also useful because Helix TeamHub lacks the function bar buttons that other tools have. However, you can easily consult the Markdown syntax via 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 to clone the wiki's Git repository.
In the repository view, you can also access the version history at the code level.
Since other tools in this overview store the wiki content in a Git repository, attaching large binary files may not be a good idea in the long run. Helix TeamHub solves this by supporting WebDAV repositories. You cannot manage the WebDAV repository from Helix TeamHub's wiki, but you can link the file from WebDAV to the wiki page. Note: WebDAV doesn't version the documents stored in it so you will probably want to handle versioning through naming conventions.
Summary of Helix TeamHub
Helix TeamHub's wiki is easy to use and gets the job done. Having side-by-side wiki editor view is an excellent way to facilitate project documentation and reference Markdown syntax. Search function for the wiki pages is also a valuable feature.
GitLab's wiki editor shares certain similarities with GitHub's and BitBucket's. It is intuitive to use and includes function bar buttons for formatting. Additionally, you'll find the cloning link in the wiki from a top navigation bar under "Git Access".
Gitlab Flavored Markdown (GFM)allows users to make some additional formatting like emojis.
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 many also prefer left-hand navigation. Those who do, may take some time getting used to navigating to the right sub-pages to find things like the cloning link.
GitHub's navigation is slightly more intuitive than the navigation in GitLab. Maybe it is the sidebar that lists all of the wiki pages you have created for your current project that makes the difference. There is also a customizable 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.
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.
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 Helix TeamHub is the no. 1 alternative to GitLab, Github, or BitBucket? Check out these sites: