I was a fan of all these little docs/diagrams-as-code standards:
- README-driven development
- ARCHITECTURE.md
- ADRs
- arc42
- C4
- etc.
Now I just put Obsidian vault inside the /docs folder of the git repo.
Instead of using somebody else’s standard, I just organize and refactor docs as I go, in the same way as I manage my personal notes in Obsidian.
Initially I wanted to use a common subset of Markdown that will work both in GitHub (GFM) and Obsidian, but then I gave up, and just use Obsidian flavor of markdown with all its proprietary features like Dataview plugin, templates, etc.
Mermaid and LaTeX is built-in in Obsidian, and there is a plugin for PlantUML.
For visual drawings/diagrams there are builtin Canvas, DrawIO and Excalidraw.
Instead of using somebody else’s standard, I just organize and refactor docs as I go, in the same way as I manage my personal notes in Obsidian.
Initially I wanted to use a common subset of Markdown that will work both in GitHub (GFM) and Obsidian, but then I gave up, and just use Obsidian flavor of markdown with all its proprietary features like Dataview plugin, templates, etc.
Mermaid and LaTeX is built-in in Obsidian, and there is a plugin for PlantUML.
For visual drawings/diagrams there are builtin Canvas, DrawIO and Excalidraw.