Alternative documentation platforms

[joelhans]

🚧 WIP 🚧

We're looking into migrating away from GitBook as the deployment platform for the Athens Research handbook. The timeline is still rough, and probably won't begin until the handbook reaches an MVP state.

This issue is meant to create discussion around the pros/cons of alternative docs platforms, and the migration as a whole. Would love some feedback or thoughts on platforms that folks might have tried!

Pros

• Establish a "docs-as-code" workflow to ensure that this repository and the deployed handbook are always in sync
• Enable more customization (styling and functionality)

Cons

• Lose visual editing capabilities, which makes certain types of contributions much easier than Git+GitHub
• Lose specific GitBook features
  • Export to PDF
  • Automatic table of contents for pages that nest other pages

Alternatives

Docusaurus

• https://docusaurus.io/
• https://github.com/facebook/docusaurus
• Robust, stable documentation deployment platform
• I (Joel) have used it professionally and successfully in the past
• Lots of stylistic and functional customization possible
• Supports MDX to embed interactive React components

Docz

• https://www.docz.site/
• https://github.com/pedronauck/docz
• Gatsby-based
  • I personally haven't had great experiences with Gatsby, but maybe Docz is abstracted enough that there isn't much dealing with GraphQL
  • Works with many existing GatsbyJS plugins, which is a plus
• Uses Gatsby's component shadowing to customize the look & feel
• Supports MDX to embed interactive React components

[tangjeff0]

Any things we can borrow from https://gitlab.com/gitlab-com/www-gitlab-com ?

[joelhans]

@tangjeff0 Good question. Looks like they use Middleman for that. A tool I used many years ago!

I also found what looks to be another docs repo: https://gitlab.com/gitlab-org/gitlab-docs. That uses a tool called Nanoc: https://nanoc.app/.

I'll have to dig in a bit more into how they publish these things because it's not immediately intuitive.