Get Hooked on GitBook

15 Jan 2018 | Categories: Software-development Writing | Tags: software-development writing ruby tools

I recently published a demo of Ruby Racko, a terminal-based card sorting game written in Ruby. Now, I’ll be the first to admit: installing and running Ruby Racko can be a bit of a pain. You don’t need to be a developer to play it, but if you have zero experience using a command-line terminal, you’re probably going to have a rough time.

With this in mind, I created a user-guide using GitBook.

Writing the user-guide proved surprisingly satisfying. Even fun! But discovering GitBook has to be the best part of the whole experience.

I’m hooked.

GitBook: Documentation Made Easy

GitBook is an open-source documentation tool that just makes sense.

Using GitBook seriously gives me the warm fuzzies. Its simple design appeals to my utilitarian leanings, and its ease of use appeases my inner lazy person. Sensible defaults abound. There’s no cruft to sift through. I feel good when I’m writing my GitBook, and best of all, GitBook’s beautiful published product makes me look good online.

I promise, nobody is paying me to say nice things about GitBook. I just really like this tool. I like to think that if more developers knew about it, there would be more – better! – documentation out there.

And better documentation makes learning easier for all of us!

Let’s GitReal

To be fair, GitBook might not be such a great fit for everyone. No tool is perfect. Some may feel, for example, that the GitBook team has erroneously sacrificed a fuller feature-set in favor of its simplistic, even “bland” design. Maybe I love GitBook so much because I’m a bland person who loves bland design.

In the interest of providing a more objective perspective, let’s take a look at some of the reasons you might LOVE or LEAVE GitBook.

Why You’ll Love It

Three Simple Templates for Specific Uses - The GitBook templates are simple and utilitarian without looking like garbage. They let your content be the star. You can choose from the following default templates:
- API Documentation (featuring a right-justified sidebar for code samples)
- Help Center (for when your users have lots of Qs and need quick As)
- Book and Manual (the simple, single-column design)
Built-In Search Functionality in All Templates - This is perhaps my favorite sensible default that GitBook boasts. Search functionality significantly increases the usability and perceived professionalism of a document; that I didn’t need to implement this myself really makes my inner lazy person happy.
Preview Your Markdown in Real-Time - Other tools probably have this too, but the split-screen markdown-editor/document-preview proved endlessly helpful throughout the writing process.
It’s Free - You can create infinite public books with this thing.
It’s Extensible - GitBook fully supports the use of plug-ins! If you prefer a little more control over the look, feel, and functionality of your documentation, you can install one of the over 700 plug-ins that are currently available (or write your own).

Why You’ll Leave It

Only Three Native Templates (and They’re Bland) - The GitBook templates are gray and white, and you can’t change the layout of the components on the page. There is an option to make each template blue instead, but if you’re looking for a wider variety of themes or color palettes, you’ll need to search through GitBook’s plug-ins.
Chrome Extensions May Cause Unhappiness - I typically use a text-editing extension in Chrome, but I now have it disabled for the GitBook website. The markdown editor was almost impossible to use before I disabled the extension.
No Native Anchor Tag Support - GitBook does not support the use of anchor tags (links that pop to a specific sub-section of a document). If you want this functionality, you need to install a plug-in.
Publishing Takes a Minute or Two - Saving your document (“publishing” it) does not instantly update the doc in real life. If quickly switching back and forth between editing your doc and viewing it in the real world is an important part of your workflow, then this may be a deal breaker.

Go On, Give GitBook a Shot!

Visit www.gitbook.com to try GitBook today! I’m like 97% sure you won’t regret it.

Beth Watson