rewrite-docs

rewrite-docs copied to clipboard

While GitBook has a good amount of benefits, there are also quite a few drawbacks that are causing significant issues. We should consider exploring alternatives to GitBook.

To outline pros / cons of GitBook:

Pros:

• ~There are beneficial metrics tracked for us. For instance, we can see what pages get the most views, what our total view count is like, and whether people like or dislike pages.~ (This is no built-in - we have to use Google Analytics for this now - but we do still have analytics once that's set up)
• They provide a clean UI that is visually appealing and means we don't have to think about styles ourselves.
• They handle the entire deployment process for us. We don't have to worry about how the markdown files are going to get copied over to the appropriate URL.
• They offer useful stylistic elements such as hints, warnings, code blocks, etc that come with colors and look good.
• They offer an editor that people can quickly make changes in and see what they visually look like.
• Gitbook does a good job of translating markdown into a simple, reasonably attractive interface. In particular the tabbed code examples are a helpful extension to standard markdown. So we can provide Gradle/Maven or Java/Groovy/Kotlin samples in the same space and have a user easily select what they're interested in.

Cons:

• Links continuously break in a variety of unexpected and annoying ways. Sometimes links will result in a broken-reference where they don't link anywhere. This randomly happens when making changes in their UI. More recently, some links have started linking to the GitHub markdown file rather than linking to the correct page in GitBook. There does not appear to be any way for us to fix this without using their UI as this is hidden meta-data behind the scenes.
• ~Their system has trouble scaling with the number of docs we have. Trying to make links in their UI can sometimes crash my browser. Even when it doesn't, it takes a minute or two per link to update as it loads the list of docs.~ This has improved over time.
• The syncing with GitHub sometimes just stops working. We've had multiple days where the docs will not sync between GitHub and GitBook. This can be extremely problematic as the docs get out of date quickly and if someone makes changes in their editor but someone else makes changes in GitHub, one of them will often be clobbered.
• Git diffs are often messed up as they randomly add (1) (1) (1) (1) ... to images or add/remove various /. This results in changes look much larger than they are and makes it harder to see what actually changed.
• The automation options are quite limited; which have lead us to create a custom markdown generator. This disconnects the generation of docs from their build and deployment, limiting what can be done easily with for instance version numbers. By comparison: AsciiDoc allows custom plugins to run as part of a build, which have full flexibility to generate docs or do replacements. We still have to manually update large parts of the docs ourselves and this is highly prone to error.

The tabbed code examples are a helpful extension to standard markdown. So we can provide Gradle/Maven or Java/Groovy/Kotlin samples in the same space and have a user easily select what they're interested in.

Another thing I've wanted that gitbook doesn't provide is some way to parameterize or template in a version number. Because updating verison numbers is a manual process they frequently get missed

I've used AsciiDoc with Antora on top quite a bit in the past and was very happy with it. This is also what Quarkus uses. It adds some complexity to the setup, but authoring is not difficult to learn.

+1 for AsciiDoc with Antora. The Spring-Framework docs switched to Antora recently too

From the community Slack, copy/pasting links does not work very well. Sometimes it only copies part of them and other times it just doesn't copy at all.

Adding another alternative here: https://markdoc.dev/docs/overview - this has the benefit of being markdown and being super extensible with code. Downside being there's a lot of code.

Another option that @timtebeek used for the spring boot workshop he's been running: https://docusaurus.io/

I spent a couple hours this morning looking into Antora + AsciiDoc. I think it has the potential to do a lot of stuff -- but the amount of work to get a site that is comparable to our GitBook site would be substantial and involve much more coding than I'd like.

Some of the issues I had with these include:

• Antora appears to be built with the desire for people to create a ton of different repositories to host different components. For instance, in their quickstart guide, they have four different repositories set up. There's one for the UI, two for individual components, and one for the core site itself. I found this to be overwhelming and complicated. There was no clear path for how I could set up a single repository for my docs. Managing multiple repositories for a single doc site is a hard-pass for me.
• Many core pieces of functionality that we need don't exist by default. Searching or tabs in the docs would involve either coding these things ourselves (as the Spring team did) or finding some extension and installing them.
• I struggled to understand the core concepts of Antora. Component? Module? Page? Content Source? antora.yml? Playbooks? There's so much there beyond just letting me write a doc. This is exacerbated by the fact that I found the Antora documentation extremely difficult to parse.

This blog post has a lot of what I felt in it. Even though it's 5 years old, it doesn't feel like these core issues have been resolved.

One bright side, though, was that it was pretty easy to get running with GitHub pages: https://github.com/mike-solomon/test-antora

For now, I'll probably try and pursue other options.

Another option that @timtebeek used for the spring boot workshop he's been running: docusaurus.io

Their comparison to gitbook: https://docusaurus.io/docs#gitbook

(BTW: A +1 for me on that)

Other alternatives:

• https://www.mkdocs.org/
• https://just-the-docs.github.io/just-the-docs/ (is too lightweight for this project)

---

Regarding ASCIIdoc - seems to be a good thing for persons used to it. Even though I never manged the switch and use Markdown wherever possible. ASCIIdoc itself is now backed by a non-profit foundation (https://projects.eclipse.org/projects/asciidoc), which makes it more sustainable.

---

In call cases, please use MADR to document the decision. Then, one can "re-use" the knowledge more easily. 😅

We've migrated our docs to use Docusaurus. The driving factor was the fact that GitBook was unable to scale to the amount of docs we have in this project. Because our docs were struggling to stay up, I had to quickly come up with a replacement plan.

As our team had experience with Docusaurus – and as we've had success with them in one-off repos in the past, I chose to use that.

I was able to mostly port the docs over by creating a fairly simple Python script. There was some minor manual work - but it only took a week or so to get all 3000+ docs working.

Some notable features that Docusaurus has that weren't available before include:

1. The ability to use variables throughout my markdown files - so I can make updates to version numbers in a shared, global spot and have them propagate to everywhere that is needed.
2. Extremely intelligent broken link checking. You can configure the site to warn or break on any broken links or broken references. Because of that, I found hundreds of issues in the docs that were previously unnoticed. This also led to us fixing some of the recipes as some of the broken links were due to misconfigured recipes.
3. More extensive customization. We can write our own CSS and we can fully control the entire UI as needed.
4. We are in complete control of the deployment process - so we aren't as susceptible to lengthy outages.

Hopefully this provides some useful context to anyone following along. Going to close this issue but feel free to reach out to me if you have any questions.

Cheers!