Technical Documentation? Here you go!

Friday, November 12, 2021 at 11:25 PM UTC

I admit: I love to write technical documentations. It's an unusual habit of a developer to do so, but somehow I adore having something to look at after a while and still be able to understand what's going on.

In the past I used several tools for that. What I can say is that word processors like MS Word are NOT suitable to write a decent documentation for software. Just do not use them.

MkDocs for the win!

I recently discovered MkDocs as the tool of my choice. This allows you to create neat online documentation as well as printable PDFs using the right plugins.

It's very easy to start with it. I use a somewhat "extended" version of it that comes with a certain style, in this case the Material design. I do not like it on my mobile devices but it makes sense on the desktop and in a browser.

Getting startet

There are several options to start with it. One includes the use of a local Python installation. This is fine. I will show you the Docker way - you just need Docker running on your machine. For all options please refer to the docs of MkDocs.

One command to rule

The easiest way to start a new documentation project is to run the following commands in a terminal window (assuming you have Docker running).

First create a new directory to store the files in:

mkdir myproject && cd myproject

Then create the needed structure and a file for MkDocs to run properly:

mkdir docs && echo "# Hi there" >> docs/index.md && echo "site_name: Docs" >> mkdocs.yml

Now you are in the doc's directory and can spin up the container that does the magic:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Finally open a browser and navigate to http://0.0.0.0:8000 - and here you go.

Once you open the index.md file with an editor of your choice (VS Code recommended to edit markdown files), you can edit the file. The browser will automatically refresh and show the changes you made.

It's mandatory to create a custom stylesheet and use it, so please refer to the docs to customize the .yml file and see what you can also add (plugins & more).

Happy documenting!






Leave a comment right here