Blog¶

Notes from my work as a software and IoT architect. They cover architecture and architecture as code, docs as code, leading engineering teams, Git, and a little computing history. There are also reviews of the books that shaped how I work. They are my own views, written to be practical rather than complete.

Browse the posts by category, or see all posts in one list.

in Team, Engineering practice
20 min read

An Approach to Engineering Leadership and Delivery

An Integrative Philosophy for Modern Engineering Leadership

Modern engineering leadership demands more than managing tasks or enforcing methodologies. It is about deliberately designing, shaping, and evolving systems in which engineers can think clearly, build effectively, and deliver outcomes that matter. Most persistent delivery, quality, and sustainability failures are not caused by a lack of effort or talent, but by the systems within which people operate. Leadership, therefore, is fundamentally a systems design discipline.

in Docs as Code
24 min read

Writing a Software Design Specification Using Docs-as-Code

A Software Design Specification (SDS) is one of the most important documents produced during a software project. It serves as the definitive technical description of how a system is intended to work, why certain decisions were made, and how various components interact with each other. When maintained well, it forms the foundation for development, testing, onboarding, auditing, and future evolution of the system.

in Docs as Code
3 min read

Deep Dive into RFCs: Capturing Collaborative Design in Docs-as-Code

RFCs — Request for Comments — are one of the most powerful tools for teams trying to make better architecture and design decisions without descending into endless meetings or tribal knowledge.

in Docs as Code
4 min read

Deep Dive into Architecture Decision Records (ADRs)

Architecture Decision Records (ADRs) are the heartbeat of traceable system design. They’re where decisions get captured, debated, and explained — not just what was chosen, but why. Without ADRs, teams rely on Slack archaeology and hearsay to understand key technical moves.

in Docs as Code
3 min read

Templates, Starter Kits and Metadata Playbooks

Every Docs-as-Code journey starts with good intentions. But without structure, even the most motivated team quickly hits friction. What’s the right format for an ADR? Where should we store risk logs? Who owns what, and how do we make it visible?

in Docs as Code
4 min read

Building a Documentation Culture That Lasts

Tools are easy. Culture is hard.

in Docs as Code
4 min read

Case Study: Multi-Layer Docs-as-Code in Practice

When you're building a product platform that spans firmware, application logic, cloud APIs, and customer-specific integration layers, documentation can quickly become fragmented and inconsistent.

in Docs as Code
5 min read

Docs-as-Code Smells and Anti-Patterns

Docs-as-Code done well can transform documentation from a last-minute task into an essential, integrated part of your engineering system. But when done badly — or worse, indifferently — it introduces a new layer of confusion, drift, and friction.

in Docs as Code
3 min read

Going Beyond Markdown: Rich, Interactive, and Cross-linked Docs

Markdown has become the lingua franca of technical documentation — and with good reason. It's lightweight, portable, and readable in its raw form. But for engineering teams building large, interrelated systems, plain Markdown often isn't enough.

in Docs as Code
3 min read

Living Architecture: Keeping Documentation Relevant Over Time

Architectural documentation has a bad reputation. People write it, forget it, and then complain that “it’s out of date” or “no one uses it.” That’s not a failure of documentation — it’s a failure of process and ownership.