log4brains VS architecture_decision_record

There is an interesting win-win tool called log4brains, that can turn your markdown into a static website. It's also integrated into MADR template. I haven’t had time to try them yet, but it's in my backlog.

I'm a solution architect in my current job, and I love it because I still get to solve technical problems and help/mentor more junior developers but I don't really write code anymore (except on minor occasions and it's mostly by choice). The tradeoff is I have to write docs and make presentations, but I learned how to do that easily enough.

I'm translating the Architecture Decision Record project to more languages. I'm seeking advice and guidance please: how are you all managing translations of git repos of content such as documentation and markdown files?

My experiments so far are here:

https://github.com/sixarm/locale-help

My work-in-progress is to create a top level directory `./locales`, then subdirectories per language using a ISO 639-1 two-letter language code, then content directories, for example:

./locales/en/hello/ (this is in English)

./locales/es/hola/ (this is in Español a.k.a. Spanish)

What do you use to track which content directories correspond to each other across languages?

The Architecture Decision Record repo is now mostly auto-translated into Spanish, French, Welsh, and Korean, in the top level directory `./locales`, using the program `slug-case` to help translate the markdown content file headlines into directory names:

https://github.com/joelparkerhenderson/architecture-decision-record

Link is https://github.com/joelparkerhenderson/architecture-decision...

Hi, article author here, we supplement our architecture diagrams with Architectural Decision Records (ADRs) https://github.com/joelparkerhenderson/architecture-decision... in the ADR we capture:

Architecture decision record by joelparkerhenderson

If anyone wants to see Polar in action on a GitHub issue, I'm experimenting with Polar on my Architecture Decision Record repo:

https://github.com/joelparkerhenderson/architecture-decision...

(I'm on the fence about the value of Polar for this kind of issue... see what you think)

This method is only slightly formalized as ADR (architecture decision record). What I personally like about templates that people share on the interned (https://github.com/joelparkerhenderson/architecture-decision-record) it that if force designed to actually consider cons of selected approach or honestly attempt to analyze alternatives.

The GitHub repo joelparkerhenderson/architecture-decision-record is a good source to get an overview of tools, articles and examples.

GitHub is prompting me to add a git successor to my open source repo, in case I die.

Do people here have advice about how to do this, or experience in doing it?

Any brainstorms about how to do it across all the related repos, orgs, etc., such as a will, or well-known file in the repo, that donates to a nonprofit, or foundation, etc.?

Here's the repo:

https://github.com/joelparkerhenderson/architecture-decision-record

Architecture Decision Records are a big help for teamwork. I have a bunch of notes and examples here, including from my time at ThoughtWorks with technology radars.

https://github.com/joelparkerhenderson/architecture-decision...

If you want to get started with ADR, I recommend looking at the repository, where you can find different ADR templates and examples of how to use them.