/ Localizando-me / blog

My first impressions of GitBook

October 2, 2019 · 7 min read · EN > reports > open collective > documentation

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.

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

Cons

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

Cons

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

Cons

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

Cons

In between

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 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. [return]

⌨️ About the author

Anna e só is a documentarian who loves working with open projects and takes pride in offering them a unique point of view. They are currently working with Open Collective as a Google Season of Docs technical writer. They are also an Outreachy helper and a technical consultant in the project Free Software Ecosystems from LAPPIS/UnB. In their spare time, they are usually breaking and rebuilding things such as this blog theme.

👋 Related posts in the Journey through Google Season of Docs series...