In the last few days I got involved in an interesting question – if you to have an internal conference with 250 presenters, multiple timeslots, live sessions, recordings, materials and more – and you need to create a website for it, what would you do?

One of the obvious choices is to write a custom app for it, has a database (document db or graph db or something similar NOSQL), a 2/3 tier architecture, etc. Or… if I’m anyway trying to understand the options around document generation, I could generate the website from some lousy excel sheets and upload to a CMS that would handle commenting and links and similar.

So I did the latter, using a little bit of XLSX parsing, use of good old Apache (N)Velocity (currently maintained by the Castle team), a little bit of window dressing and figuring out some stupid limitations around transposing arrays with double nested loops using the Velocity language, and:

Every good project need good documentation, and every good documentation needs a good engine to create and maintain it with.

So, am I going to chose Jekyll for maintaining the (currently mostly empty) ComposeUI documentation site | A WPF .NET Core based, WebView2 using UI Container for hybrid web-desktop applications (morganstanley.com) website? Most likely not. We currently have quite a few contenders for documentation generators – so no, most likely it is not going to be Jekyll our final choice (although nice to have a native support from gh-pages for it for sure, and gives an opportunity excuse to learn a new language and technology, Ruby and the Gems). Contenders are now: Jekyll, Hugo, Docosaurus, Docute, Docsify, Sphinx, Doxygen, etc. Each have their pros and cons, and it is not necessarily that we would only chose one of them. Also, whenever possible, we would aim to generate as much of it as possible – not due lazyness, rather to make sure it is always updated whenever we touch the source code.

So do bear with us, soon we would fill the documentation site with some basic (Jekyll) content before finding out our choice of documentation generator(s).