architecture-decision VS asciiflow

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:

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)

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...

The article mentions Architectural Design Records (ADR) which can be included as a folder in the git repo for the project, as a means of documenting the historical decisions that led to the project's current structure. Some of that seems overly complex or formalized (i.e. reinventing UML and all the problems that came with it), but having that history in some kind of constant format would likely help overcome any novelty issues and help people grasp what's going on. The simplest format discussed seems the best for most cases:

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

> 7. You can put them in the source where they are relevant.

> Got a hairy state machine? Stick a comment at the top with something like nomnoml's syntax and anyone can follow what's going on without having to trace through the code.

For that use-case a markup graph language is a poor solution. Use https://asciiflow.com instead to produce something that people can digest without needing a third-party tool that may not even exist anymore.

Many diagrams I am able to draw manually as I'm editing source code on emacs, but for more complicated ones I tend to use this: https://asciiflow.com . To each their own, so pick your favorite ASCII editor.

This isn't at all what you are asking for but I use it in code all the time for flow-charting logic. https://asciiflow.com/ And on the plus side, the output is very portable.

Combination of: - http://maaslalani.com/slides/ - for slides - figlet/toilet/cowsay/lolcat - for generating titles and ascii art - https://github.com/lewish/asciiflow - for charts and diagrams

So I used this website: https://asciiflow.com to draw out the diagrams and then pasted them into the LCDs using the monospace font! An LCD is 39x58 "ASCII tiles" FYI if you wanted to do this too!

AsciiFlow