Migrate the book from gitbook to...

[enilsen16]

There are some issues with gitbook (mainly that I think you'll no longer be able to self host it). Since we use hugo in other places, it makes sense to use it for the book as well. Though the problem with hugo is that themes need to be checked in as git submodules.

theme options:

• https://github.com/vjeantet/hugo-theme-docDock
• http://themes.gohugo.io/theme/material-docs/

We can use Algolia's DocSearch for searching documentation.

Another option could be https://docusaurus.io/en/

[SeanTAllen]

There's a Gitbook hugo theme on Github. I can't find the link at the moment but I sent it to @JONBRWN a while ago, he should have it.

[JONBRWN]

@enilsen16 here's the Gitbook theme for Hugo: https://github.com/blezek/bookish

[aturley]

I'd like to see an enumerated list of why we think we need to move. I remember when we chose gitbook there were some complaints about it and we decided to use it anyway. Are there new issues that have come up since then? Is it only the self-hosting issue? What criteria to we want a new solution to meet? How will we evaluate the options?

[SeanTAllen]

Many @aturley. Amongst them:

• Its largely unsupported at this point. I would say "falling into disrepair" would be a good statement.
• It has bugs related to variables that require us to use tools like sed/awk to work around.
• Its horrible for API documentation (this isnt gitbook specific, it's a "only markdown available" problem).

[enilsen16]

Unrelated side-note, Algolia has crawled our current documentation. The configuration is available here: https://github.com/algolia/docsearch-configs/blob/master/configs/wallaroolabs.json

[enilsen16]

TL;DR: After looking into Hugo more I think in the long run it be just as problematic as Gitbook. After looking at the options I think I prefer docusaurus. We can always get hacker news or lobste.rs's opinion too.

Hugo

---

Pros:

• Blog already uses hugo
• Decent sized user base
• Easy to work with-ish (Theme management isn't great)

Cons:

• Not really designed for documentation
• No built-in search capability (Algolia does support it though, just externally)
• Themes are checked in as git submodules (Updating themes otherwise would be an even bigger pain)
• The gitbook look-alike theme hasn't been updated since 2015

Not to say there aren't projects using Hugo for docs though. For example:

• https://docs.pupil-labs.com/#getting-started

Personally I think Docusaurus is a better option. For the reasons below.

Docusaurus

---

Pros:

• Designed for documentation (Though it does include an optional landing page and a blog)
• Easy to work with and update (even when CSS is updated)
• Default theme looks fine (Will require some tweaks, but that's fine)
• Built-in support for Algolia searching (Assuming they've crawled your site before hand)

Cons:

• Newer than hugo, really only popular in the Facebook JS community
• Means using yet another static site generator (Though Nodejs is already a dependency of Wallaroo)

Example:

• https://facebook.github.io/react-native

Docusaurus also dogfood themselves: https://docusaurus.io/

---

Both options can include the ability to version documentation as well, which is currently something we do not have.

WDYT?

cc/ @rachelblasucci @JONBRWN

[SeanTAllen]

I think we need to step back and enumerate what we are looking for:

Examples...

• Easy installation for development (single binary nature of Hugo is great here)
• Good for API documentation as well as more tutorial style (purely markdown based GitBook was very bad here, the facebook react native stuff for API, I find hard to navigate. I don't think its particularly good. Hugo, is very flexible, I suspect we could make it good for this)
• Searchable
• Versionable
• "Template variables" - ability as part of an automated build process to inject values into the build to change things like urls, versions etc. Gitbook and Hugo can both do this. Gitbook due to a bug doesn't do variable substitution in code blocks. That's been a problem for us.

Nice to have:

• "Easy to contribute to" ie the process of contributing to our docs, it should be easy.
• PR'able previews of changes. We get this if we use something that works with and is hosted on Netlify. Its wonderful for the Pony website for example, each PR you can go and get a full version of the website as it would look with the PR.

What else am I missing? What do folks think isn't needed from the list.

[enilsen16]

Other examples:

• Maintainability and easy to update

Additional nice to haves:

• Works well offline (Whether you want to view the documentation in the terminal, in the browser or in a program like Zeal. Would be nice if documentation is formatted in a nice way).

• Would be nice if when a style change is made, all versions of the documentation are rebuilt rather than just the latest (Help avoid issues where old documentation is broken on safari or on mobile).

[enilsen16]

WRT the Hugo and/or Docusaurus discussion:

I'm concerned that we will end up maintaining a custom theme for Hugo to get the documentation-like features we want. Which is going to only make maintainability harder.

There there is no perfect solution. I just feel something where the default theme includes the features we want, will in the long run require less work.

It's probably best to just bring this up in the next sync as I feel like we could go back and forth forever.

[SeanTAllen]

From a branding perspective, we are probably going to end up with a custom theme. So, it's not something that concerns me a lot.

[enilsen16]

From a branding perspective, we are probably going to end up with a custom theme. So, it's not something that concerns me a lot.

Sure. I guess in my mind changing some colors is difference than maintaining a entire theme. Then again if this was the plan all along, I'm fine with Hugo.

[SeanTAllen]

I'd like to see how options stack up against requirements.

[JONBRWN]

My thoughts:

I don't love Hugo as the replacement choice, but it's a better option than Gitbook. The theme management isn't that big of a problem, we've had no issue with the blog and our custom theme. We've also had everyone run it locally without a problem.

I wouldn't rely on the NodeJS dependency of the MonitoringHub in regards to Docusaurus, there was enough resistance on the install of that plus Erlang/Elixir that we decided that a Docker image to do the building was the best option. Although handy, it is another thing to maintain.

I still think there might be some value in reaching out to the dev community via HN/Lobsters to see what people are currently using and what they like/dislike about it.

[pzel]

A bit late in the game, but I wanted to share my faded-yet-positive recollections of using readthedocs for plain-vanilla open source documentation.

[enilsen16]

I also forgot to mention, It's quite possible that we end up going with two solutions. One for docs and another for more book/tutorial like walkthroughs...

[enilsen16]

	Hugo	Docusaurus	ReadtheDocs
Easy to theme
Maintainable
Uses Markdown
Searchable
Works well offline
Easy Installation
Works with Netlify
Template Variables
Versioning

The top row is the options we are considering and the first column is our requirements. Please let me know by 9/12 if you have thoughts on other options or requirements that I am missing above.

[jtfmumm]

@SeanTAllen Can we close this?