re: Where do you keep non-code documentation, such as architecture explanation or research? VIEW POST


Great question!

I use AsciiDoc ( to write my docs and treat it as code (search for "docs-as-code" or "docs-like-code"). So I just store it along with my code or in its own repository if it belongs not directly to the code or is written before you code like architecture docs.

Most git frontends like bitbucket and github support the direct rendering of AsciiDoc, but I've build up a toolchain which helps me to maintain my docs. It is called docToolchain and can be found on github:

It helps me to automatically update diagrams, render the docs as PDF or publish it to Confluence. The Confluence feature is IMHO the best - it allows you to let people read your docs in a wiki while you maintain them in Git.

A presentation on the thoughts behind it can be found at

code of conduct - report abuse