← Homepage

[Season of Docs] · · 7 min read

My first impressions of GitBook

In two years working with open projects, I have used a couple of different platforms and/or frameworks to organize and manage documentation: MediaWiki, DokuWiki, GitHub and GitLab repositories, wikis and pages, Hugo, and finally, GitBook. But before diving in my experiences with GitBook, let me share with you my perception of the ones I’ve used the most.

Documentation platforms & tools I’m familiar with

MediaWiki

Developed for Wikipedia in 2002, MediaWiki is the software behind many of Wikimedia projects. Published under the license GPLv2+, MediaWiki was created to provide a highly collaborative and easily scalable platform using the wiki format. Available in 428 languages1, it offers a version control system for each page, anonymous contributions (if enabled) and a multitude of tools thanks to its plug-in system.

While it’s a great software for the Wikimedia community and a few others such as Arch Linux, I would not recommend it for small to medium projects: setting it up can be difficult and often confusing; it has a steep learning curve; and projects of that size would probably benefit more from simpler platforms. If your team members and/or your community are familiar with wiki markup, however, it may be an interesting and flexible software to incorporate into your infrastructure.

Tainacan used MediaWiki to manage their documentation for a brief period of time – but as their team shrinked due to financial hardships, they decided to transfer their user and developer guides to Docsify. The amount of maintainance work MediaWiki requires wasn’t worth it for such a small team.

Pros

  • Maintained by the Wikimedia Foundation and the Wikimedia community
  • Supports a wide range of languages
  • Diverse plugin ecossystem
  • Works fantastically for bigger communities due to its scalability

Cons

  • Documentation is often confusing or lacking
  • Complex management system server-side and in the web platform
  • Overkill for small and medium communities

Resources

This is one of the simpler approaches on that list. For some projects, a few Markdown files on a platform such as GitHub or GitLab are enough. Outreachy’s onboarding and internal documentation, for instance, is currently hosted on GitLab – and there is no need to change it the way it is. Those files are only accessed by a handful of people and each one of them is familiar with those platforms. Git tracks the history of our edits and we can use tools such as Pull Requests and Issues to suggest changes and have private discussions with a retrievable log. It’s also easy to add or remove collaborators, and if you don’t use self-hosted solutions, documentarians won’t have to create yet another account.

Pros

  • Simple, easy to set and manage
  • Git integration
  • Most popular platforms support a flavor of Markdown
  • Collaboration between team members and external contributors is easy to manage

Cons

  • Those who aren’t familiar with Git may need help understanding the platform and workflow
  • Too raw – repositories offer no customization and they can be quite user hostile

If you are looking for something more structured, both GitHub and GitLab offer built-in wikis. There aren’t customization options still, but navigation and separation between pages and sections of a documentation is a bit better. Oh my zsh wiki uses a GitHub wiki to guide their users.

Pros

  • More structured and user-friendly than repositories
  • Not too difficult to set up; you can add it to existing repositories in a few clicks

Cons

  • It also doesn’t offer any kind of customization; depending on your use, it can be quite limited

GitHub and GitLab also offer their own flavor of Pages, a feature that allows you to serve static websites hosted by them. You are able to use Jekyll, Gatsby, Hexo and many more.

This blog and my professional website are both deployed and served by GitLab Pages, and generated using Hugo. Kubernetes also uses Hugo to generate their website and their documentation.

Pros

  • Easier to use than solutions such as MediaWiki
  • Flexible and customizable

Cons

  • Many of them don’t offer a user-friendly interface to edit content – all contributors will have to either edit files on GitHub or locally on their computers

In between

  • No database – documentation containing thousands of pages may be difficult to manage with those systems, but smaller ones will find this a good thing

GitBook

GitBook used to be an open source CLI tool to generate documentation from Markdown files using Git. If you are familiar with the Django Girls tutorial, you have seen a good example what their tool was capable of creating.

Today, they are a platform that promises to help you build your documentation with both team members and external contributors in an easy way… And much of the spirit of their legacy tool was lost in that transition.

Open Collective’s contribution guide

One of my most important tasks in the last few weeks was revamping Open Collective’s contribution guide for documentation. It only taught potential contributors how to edit existing pages – important tasks such as adding new pages or adding media weren’t covered, and it didn’t explain much about what all those Git things are. It presumed external contributors had a certain level technical knowledge and it didn’t help much any potential contributors who didn’t.

Open Collective’s documentation also needed a style guide to consolidate all conventions their core contributors created: things like what terms documentarians should use to refer to certain functionalities and personas, writing style, media usage.

Working on those two pages made me realize that along with the Welcome page, the Suggesting changes and Style guide pages will always be a work in progress – and while there are some good reasons, others aren’t as good.

To write the Suggesting changes page, I had to work as an external contributor submitting changes through GitHub only – and GitBook’s integration with GitHub reminds me of the time I tried to play The Witness: just when I thought I cracked the code and truly understood the puzzle, the next challenge would prove me wrong. Worst of all, I can’t use other methods than trial and error to test my understanding of the platform and GitBook’s behavior can be so unpredictable at times there is no way to be completely sure I’m getting something right.

One of the most recent incidents was changing the organization of all pages through GitBook. On Open Collective’s GitBook, only a couple of changes seemed to be accepted by GitBook – others simply didn’t make it. To make things even weirder, when I created another GitBook with the exact same files, all of those changes were accepted without any issues. Exploring the administrative interface, I found out that GitBook did create all groups of pages I requested via GitHub, but for some unknown reason they weren’t being displayed. 🤷

Welcome page

We want to create a welcome page that will help readers to find the information they are looking for in a easy way. To do that, we need to understand how our users interact with our documentation: do they use the search bar? Do they have to click on many pages before finding the right answer? Does our traffic originates only from engine searches, our own application and our support channels or do our users know where to search for further information?

We can do surveys to answer those questions, but in our case analytics can also be a great evaluation tool. However, GitBook (1) only supports Google Analytics (a product we don’t want to use) and (2) it doesn’t do much with it. The only information you will get with Google Analytics integration is page views.

The most frustrating thing about GitBook is that its previous version was a lot more permissive and flexible than the current one – for instance, it allowed the use of third party plug-ins. They incorporated the most popular ones to their codebase to give them official support and that’s pretty cool, but their sudden change of heart makes a case for not depending on software or servers you can’t control.

Summing up

  • GitBook can be a great tool for core teams – it offers a WYSWYG editor, useful shortcodes, multiple draft support
  • However, external collaborators may struggle to contribute due to their limited, poorly documented and often buggy GitHub integration
  • GitBook doesn’t support any other analytics than Google’s – and it only offers a report on the amount of views each page had
  • Their Markdown to HTML implementation doesn’t follow the conventional format and, in certain occasions, it goes against W3C’s guidelines on accessibility

GitBook certainly has cool features, but it’s too easy to stumble upon its limitations – it’s just a matter of wanting to do something more.

  1. Source: Article about MediaWiki on the Angolophone Wikipedia. ↩︎