OS 004: Publish Technical Documentation Through Static Website

OS-004 Publish Technical Documentation Through Static Website

Date: 2020-01-01

Status

Implemented

Context

OS 004 head

Legible, well-structured and up-to-date technical documentation of released open source components is a service to all our users. Due to the small size of our team, we want a straight forward tool chain to generate the website. In the future, we could move our product to another hosting platform. The solution should be built on a standard to minimize porting overhead.

I am personally a fan of Asciidoc and would promote a solution supporting this markup language. I will strongly fight against proprietary solutions.

Decision

  1. All our technical documentation and blogs will be written in Asciidoc.

  2. The website is created using the Hugo toolchain.

  3. The theme of hugo will be Docsy.

Consequences

  • Committers are forced to document in Asciidoc.

  • Tooling is slightly more brittle because Asciidoctor integration in Hugo is work in progress. Asciidoctor is also undergoing changes such as the native support of rouge syntax highlighter. The improvements in both tools were impressive the last year, but we have to regularly update our toolchain and update all Asciidoc documents.

Learnings

  • (ref-hugo) themes styling for Asciidoc is sketchy. The visual quality is currently hindered due to faulty support of the standard or custom AsciiDoc stylesheet.

  • Asciidoc supports native rouge code highlighting module. All source code fragments are nicely displayed without special support from Hugo.

We documented our experience in various blogs [1] [2]>. We use currently the Google sponsored theme Docsy for our static website.

Links

  • [1] tangly blog/2020/creating-a-technical-website-with-hugo-and-asciidoc/[Creating a Technical Website with Hugo and AsciiDoc]

  • [2] tangly blog/2020/support-comments-for-static-hugo-website/[Support Comments for Static Hugo Website]