DEV Community

The Potato Head
The Potato Head

Posted on

Possibly The Ultimate Technical Documentation Guide, maybe.

### Note - starting to write articles so any feedback greatly appreciated.


Managing technical documentation is Haaaard. Everyone will write it but no one will maintain it. Confluence, Readme, Gitbook, Read the Docs etc. etc. all serve a great purpose, however, if you really want the latest documentation for your systems and departments then let's dive right in!

If you haven't got time to read then you can view the results here

Or, if you just want to source code with tutorial visit the github repo

What is it?

docker + Mkdocs + Mkdocs plugins + mermaid + meta

Show me then

Install the repository

git clone
cd mkdocs-example.demo
cd docs
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Visit localhost:8124

Ok, but what else?

Multiple Repositories

By simply using a tool such as you can pull many repositories into a central repository = great for observing multiple projects and centralising documentation. All you have to do is include the external repository's mkdocs.yaml as seen below:

  - External Repository: '*include ./second-repo/mkdocs.yml'
Enter fullscreen mode Exit fullscreen mode

Draw io integration

By using the VSCode extension, you can diagram in the code editor and view it in your MKdocs!

Image description

Mermaid Diagramming

If you have the appetite for it you can diagram in code by using mermaid syntax. Although there is a learning curve, the benefits of diagramming next to your code outweighs the learning time.

Image description

Open api Integration

If you keep true to your api specification and definitions then you can publish your local definitions to your documentation (again useful for poly-repos and contracts).

Image description


Mkdocs isn't for everybody but it does satisfy developer requirements. The extensibility, git history and rapid access that Mkdocs gives you will truly make your Dev experience more enjoyable. Not only can you build quickly but you can also publish to Github pages, cloud-front and netlify with ease!

Give it a go!

Top comments (0)