Arialine articles
Diagrams are easy to draw. Keeping them true is the hard part.
Field notes for engineering and product teams working through architecture, Mermaid, technical decisions, and Slack.
Featured
Architecture diagrams for embedded systems and firmware reviews
Firmware diagrams become unmaintainable when every signal, threshold, and subsystem interaction is forced into one static drawing.
The archive
All articles
40 published
02How to keep complex Mermaid architecture diagrams readable
When a Mermaid diagram becomes a hairball, the solution is usually scope and hierarchy, not more layout directives.
GuideJul 15, 20262 min read
03Code-generated diagrams and decision-captured diagrams solve different problems
Code generation explains what exists; decision capture explains why it exists and which alternatives the team rejected.
GuideJul 15, 20262 min read
04How to use AI for architecture documentation without inventing your system
AI is most useful as a collector, drafter, and reviewer; humans must verify architecture claims against code, tests, configs, and accepted decisions.
GuideJul 15, 20262 min read
05From whiteboard photo to Mermaid: a practical architecture workflow
Whiteboards are excellent for thinking; Mermaid is better for maintaining the result. The workflow should connect them without redrawing from scratch.
GuideJul 15, 20262 min read
06Diagrams as code vs conversation-led diagrams: which source of truth should win?
Repository diagrams align with implementation; conversation-led diagrams preserve intent and review. Mature teams often need both.
GuideJul 15, 20262 min read
07When to archive, delete, or simplify stale architecture documentation
Not every stale artifact should be updated; some should become clearly labeled history, be simplified, or be removed.
GuideJul 15, 20262 min read
08How often should architecture diagrams be updated?
Architecture diagrams should be updated when represented facts change, with periodic reviews used only to catch missed updates.
GuideJul 15, 20262 min read
09Use new hires to test whether your architecture documentation is actually useful
New hires are the best test readers because they expose missing assumptions that experienced team members no longer notice.
GuideJul 15, 20262 min read
Showing 9 of 40 articles