GitBook – You Can Document Everything!

I think it’s no secret that developers hate paperwork. We like solving complex problems and exploring new frameworks and libraries. We like writing documentation about as much as we like instant coffee…

At SSW we’ve enjoyed automating everything from the 100 steps that happen for a new hire, to the daily chore of entering timesheets. Less enjoyable is writing documentation for our projects (Markdown & GitBook), and documenting all the SSW Rules (Markdown, GitHub and Gatsby).

When I saw Jason Taylor also using GitBook to document the Clean Architecture Workshop, I thought that was awesome.🀯

Video: SSW’s Jason Taylor and Adam Cogan talk about building fantastic documentation using GitBook

End-User Documentation

GitBook is a fun way to write online documentation using nothing more than a web browser. You can use it for anything from taking personal notes, to creating knowledge bases or product documentation.

I think it has revolutionised the way we run our training courses by reducing the amount of preparation time we need before running a course and it gives students something to follow other than a PowerPoint presentation. Creating a workbook on GitBook is a great way to help students learn at their own pace and to keep your content current.

Here’s a quick comparison for GitBook compared to a Word document or Plain HTML pages:

A Word Document

βœ”οΈ Content – Easy to edit
βœ”οΈ Navigation – Has nice navigation on the left
βœ”οΈ $ – Free to use
βœ”οΈ Can create a PDF

❌ Copying Code – No code elements for technical training
❌ No Google Analytics
❌ Not native to the web
❌ Not easy to collaborate – real time sharing is glitchy

Plain HTML pages

βœ”οΈ You have complete control over how it looks
βœ”οΈ Can add Google Analytics

βœ”οΈ Can create a PDF

❌ Nothing is out of the box you have to make everything yourself
❌ Content – Hard to edit using HTML
❌ Navigation – Does not have any navigation
❌ Lacks basic features, like search
❌ $ – You have to pay for hosting
❌ Can’t collaborate easily

GitBook

βœ”οΈ Content – It’s in Markdown & has a great WYSIWYG editor
βœ”οΈ You can have rich content and rich text**
βœ”οΈ Awesome collaboration – you can invite people to your team
βœ”οΈ Integration with Slack, Intercom, GitHub etc.
βœ”οΈ Navigation – Has nice navigation on the left
βœ”οΈ Copying Code – If you have code elements for technical training it allows easy copying and pasting
βœ”οΈ $ – The base version is free for everyone
βœ”οΈ $ – The full version is free for open-source communities
βœ”οΈ It allows you to add a custom domain
βœ”οΈ You can synchronize your content with GitHub
βœ”οΈ Integrated search
βœ”οΈ Integrated with Google Analytics
βœ”οΈ $ – Can create a PDF
, but it’s a paid feature

❌ There’s no inline highlighting for code blocks (as Jason says in the video)
❌ You can’t support different version of the same document, v1, v2 etc.
❌ $ – The Team version can get expensive (but no more than upkeeping a domain!)

❌ No auto save. You need to click save or else you can lose information

Developer Feedback

I asked our team at SSW what they used for different types of documentation, and the overwhelming majority said they choose GitBook for End User documentation as well as creating Knowledge bases. You can see the results below:

Figure: GitBook (red) was the overwhelming winner for End User Documentation
Figure: Gitbook (orange) also stood out as the leading tech to build a knowledge base.

Have you used GitBook yet, or seen some other awesome documentation? I love hearing other people’s experiences. πŸ™β­