Handbook: Ghost vs Gitbook vs Docusaurus

Archive
1

Hey there,

Our handbook is currently hosted on Ghost using the Casper theme. As part of updating the team handbook project, we’re exploring different templates and tools with a friendlier design and features for knowledge bases.

I’d like to get your thoughts on this topic, and test discuss for this type of discussion :slight_smile:

What we’re looking for
Basic

  • Navigation: sidebar TOC/breadcrumb
  • Search functionality
  • Custom branding
  • Intuitive knowledge base design
  • Alignment with our principles and values

Pro

  • Custom table of content
  • Async collaboration

After some research, here’s a shortlist of options

Async collaboration and document versioning
The main difference between Ghost and Docusaurus or Gitbook is that Ghost is a tool for publications vs Docusaurus/Gitbook that are focused on knowledge bases. Therefore the latter is better prepared for async collaboration and document versioning.

This is an important feature as the handbook is a team resource but most people only have view access, limiting the ability to make suggestions and collectively improving it.

Ghost has a membership feature but AFAIK it’s for the paid-subscription model.

Alignment with our principles and values
Ghost > Docusaurus > Gitbook

It might be relevant to note that Ghost is open-source and non-profit, Docusaurus is open-source, and Gitbook is free only for open-source or non-profits.

Thoughts? Comment below, please :eyes:

My two cents
Ghost

  • Pros: alignment, change of theme vs change of platform
  • Cons: it’s challenging to have a customize how content is organized, not collaboration friendly

Docusaurus/Gitbook

  • Pros: ready for knowledge bases, collaboration friendly
  • Cons: Gitbook is shifting away from the OOS ethos, Docusaurus might be overkill to set up and we might want to prioritize basic over pro features
3 Likes
2

Nimbus team already uses mdBook which is quite fast(written in Rust) and produces very nice clean docs:

It’s like Docusauris in that it simply converts a bunch of markdown files into a page with sidebar table of contents and search. Very basic really. No wysiwyg like in Ghost.

3 Likes
3

Hey Monica, first of all, thank you for the brilliant idea. I believe it will be a great step for HR processes.

If we are talking about collaboration, Ghost is not the best solution like Gitbook or Docusaurus. Still, it is possible to do everything you want with Ghost.

IMO, if it is not going to be hard to use for you (and the HR team), we can go with the mdBook, as Jakub said. But if it will be hard to use for the HR team, probably Ghost is the more straightforward solution to use.

1 Like
4

Thanks for your input guys! I’m now more leaning towards either Docusaurus or mdBooks because of Github integration and collaboration features, I like mdBooks’ simplicity but I have a slight preference for Docusaurus since it gives you more options to customize it.

It seems like either of them will integrate better with how the rest of the org documents stuff vs Ghost :slight_smile:

Would love to have @froy’s thoughts on this as he’s doing similar research.

2 Likes
5

cross posting this (related) → https://discuss.status.im/t/announcement-security-revamp/2282/2

1 Like
6

hi,

I am going with mdBook because as @jakubgs pointed out, it is already used by the Nimbus team, it accepts raw static Markdown files (which is not the case of ghost), it’s written in Rust and it’s apparently easy to setup.

In my case, having raw static Markdown files is critical as I write faster in markdown than in a WYSIWYG editor, I also want GitHub PRs to review the work so that I don’t introduce new tooling to write documentation.

I do find Docusarus sexier but sexiness is not an attribute I need: clear, readable and simple interface is what developers need to easily read my doc :slight_smile:

3 Likes
7

May I also add that GitLab uses a public, GitLab hosted, handbook for all company matters. Meaning that engineering but also, legal and marketing document their processes and guides etc in GitLab. I love the concept because GitLab/GitHub are tools that facilitate asynchronous discussion, search and improvement.
Similar to opensource code, we can reach a stage where anyone can open an issue or even a PR to propose an improvement to a process and kickstart a discussion around it.

3 Likes
8

I’d be absolutely in favour of all using Github, for all the reasons you outlined, @froy - even if it might be a bit of a learning curve for our team.

2 Likes
9

Thanks everyone for the input on this topic! It seems like we’re all aligned on using Github and mdbooks seems to be the go-to tool across the team.

We’re also going for this combo for the handbook for the same reasons stated above: easy to setup, other teams are already using it so it creates homogeneity of knowledge bases, it has all (search, table of contents, etc.) features needed, and it facilitates async collaboration bridging teams.

I’m excited that the people ops team is open to move to Github and get closer to the dev-side of the org :star_struck: Count on me to help with the transition till everyone’s familiar with Github if needed!

@jakubgs I’ll DM you to coordinate the setup.

2 Likes