[splittingTimes]

Great article on the topic. Biggest takeaway is how they added linters and link checkers to the toolchain.

We currently try to establish something similar on our end using AsciiDoc [1] as fileformat, Antora [2] to build the site and hosting on Azure storage. AsciiDoc has a bit more features compared to Markdown which allows for a richer presentation of the docs.

Biggest difference is that Linode has the docs in a separate repository. Not sure if it is a limitation of their toolchain or a deliberate decision.

Antora allows you to have the project documentation in the actual project repositories. It then pulls the docs from all the different repos together to build the site. This also allows you to have the released product versions go in-synch with the docs versions. Antora builds each version of the product as part of one site. The reader can explore different product versions or navigate between pages across versions.

===

[1] https://asciidoc.org/

[2] https://antora.org/