I'm a big proponent of contract and document based development. Easing on boarding, and correlating the current architecture with active documentation. I usually keep software centric, in git along side the code.
Coming from Python I was a big fan of sphinx. With Graphviz we were able to embed flow charts of micro services. It worked very well. There are a number of extensions made it very powerful.
I switched because it felt close to markdown but not markdown. I now use docsify[0].js. There are a few things I miss. But it's an easier transition as my docstrings are also markdown. So no context switching.
Markdown is very bare. But that I feel keeps the documentation simple. With less knobs to twist, the documentation has less accents to it. With that limited range
I feel it's more important to have a style guide.
Coming from Python I was a big fan of sphinx. With Graphviz we were able to embed flow charts of micro services. It worked very well. There are a number of extensions made it very powerful.
I switched because it felt close to markdown but not markdown. I now use docsify[0].js. There are a few things I miss. But it's an easier transition as my docstrings are also markdown. So no context switching.
Markdown is very bare. But that I feel keeps the documentation simple. With less knobs to twist, the documentation has less accents to it. With that limited range I feel it's more important to have a style guide.
[0] https://docsify.js.org/#/