Luckily outside of engineering they don't use our confluence. So the target audience is technical.
Any advice here or questions are welcomed. Thank you.
Checkout Bookstack https://www.bookstackapp.com/
They always getting out of sync and eventually abandoned.
Just store markdown files under the /docs/ folder in the git repo.
yes, if they're don't change frequently by non-technical people. There are tools allowing conversion between GDocs and markdown. So one can start with the GDoc at the initial non-tech collaboration stage, and once it's more or less stabilized, convert it to markdown and commit to a git repo.
> system design docs
yes - see C4-PlantUML[1]
> meeting notes
no, unless they're directly code related like ADRs [2,3].
Although, one can abuse Github Issues + comments for this, in my opinion it's better to use modern SaaS tools in this case, e.g. Loom, Descript, otter/gong, etc. - you can automate this process, e.g. transcribe the meeting's recording and add the issue/repo using Github Actions.
> etc.
To summarize: any piece of documentation/diagrams that has even minimal affinity to the source code and can be expressed in a text-based format.
I even store visual non-text based diagrams (non-manually editable XML) using Draw.io VSCode extension [4], or Miro board backups/dumps.
Use linters and automate with CI/CD (e.g. Github Actions).
Also I suggest to have a list of VSCode extensions for each text/diagramming format used in the repo. Maybe with the script to automate their installation.
--
[1] https://github.com/plantuml-stdlib/C4-PlantUML
[3] https://docs.aws.amazon.com/prescriptive-guidance/latest/arc...
[4] https://marketplace.visualstudio.com/items?itemName=hediet.v...
You have me sold, friend.