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.🤯
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:
Have you used GitBook yet, or seen some other awesome documentation? I love hearing other people’s experiences. 🙏⭐