Documentation as Code makes it first class citizen while developing

Documentation as code states that you store the documentation of your
project/service at the same location where you store you code.
This has some clear advantages:

• You don’t need to search for you documentation, everybody is aware where it is and how to extend it
• You can update the documentation for an issue in the same pull/merge-request where you make the respective technical changes.
• If the documentation uses the same quality process as code you can ensure its quality
• You can make building the documentation part of your build process and therefore include test results,
  static code analyzer results, code documentation and so on in your documentation deployment.

The only downside is, that developers usually do not enjoy writing documentation and if you store it in your repository,
you are going to have a technical overhead for building and deploying the documentation.

That being said I still love the documentation stored in the repository because every developer I’ve met in my career,
loves a well written one.

Static web page generators are easy to use

To implement Documentation as Code there are various tool out there.
They are mostly static web page generators with a more or less sophisticated templating engine.
You can write your documentation in markdown and they will assemble and build a html page or even a pdf or confluence export from it.

AsciiDoc

• (+) Easy to use

• (+) Gradle plugin

• (+) pdf export

• (-) No document index

• (-) No search function

• (-) No theming

I like AsciiDoc because its really easy to use and write documentation.
I would suggest it for small to middle sized projects because it lacks some feature like document index, search, theming.

Jekyll

• (+) used for github pages

• (+) theming

• (+) searching

• (+) plugin system

• (-) I didn’t got it to run on my windows pc (it is written in ruby and needs some native bindings I could not install)

• (-) lacks some feature like: page including

• (-) slow builds

I tried Jekyll once for my github project but couldn’t get it to run on my developer machine and therefore my opinion
may be biased against it.

Hugo

• (+) really fast build process

• (+) extensive theming which makes hugo suitable for many cases

• (+) rapidly growing community

• (+) searching in some themes

• (-) no plugin system

• (-) go template syntax is sometimes really weird

I like hugo because of the enormous amount of possibilities the theming gives.
I can install on any operating systems (windows, linux, max) I encountered so far.
Its quite easy to integrate in build pipelines but to be fair not as easy as using the asciidoc gradle plugin.

You can deploy the documentation through docker or by just copying to a apache/nginx server

Deployment of the build documentation is fairly easy.
The compiled html/css/js files just need a static web page server like apache or nginx .

You just have to copy it to their web serving directory (using ssh or ftp) and start using your documentation.

Or you could write a small docker file and deploy it to Kubernetes, OpenShift, etc:

FROM nginx:alpine
COPY hugo/public /usr/share/nginx/html

Wrapping it up

• Documentation as code improves the quality of the documentation
• It makes documentation more accessible for developers
• You can easily build it through static web page generators and deploy it to a web server

We use documentation as code for our open source project keycloakmigration

If you want to have a look you can simply look into the docsbuild folder where the documentation sources are.

Github expects the compiled html documentation in /docs so we could not use this dir and need to copy the compiled html files there.