solution-design

I rebuilt this site's Makefile in Task to judge the two properly. The trap is stacking the deck against a rotten Makefile — so I brought mine to its best first, then weighed Make against Task, round by round.

Why I added comments, what I evaluated, and why I went with Hyvor Talk — on a static Astro site, DevOps overhead and vendor tracking are both non-starters.

The opinionated stack I've formalized after building the same kind of application too many times ad-hoc — the philosophy, principles, technology choices, the roads not taken, and why. A formalized hypothesis: individual pieces tested in practice, the combination still proving itself.

A structured evaluation of ten documentation platforms — Docusaurus, VitePress, Starlight, Doks, Material for MkDocs, Antora, and more — against requirements for versioned, long-running documentation projects. Covers performance, versioning, search, and ecosystem viability, with scoring tables, a progressive elimination process, and an incremental implementation plan built around Starlight. Starting from the needs of the Digital Solution Lifecycle Model and its companion tooling, but intended as a reusable approach for future projects.

Each of the Ten Views of a digital solution has a natural diagram type and a tool that produces it well. This post maps them one view at a time — using PlantUML, Mermaid, BPMN.io, and DBML, with a consistent running example of a small online bookshop and source included for every diagram. A cross-reference matrix summarises the full mapping at the end.

Most digital solutions are documented partially — the technical parts get captured, the rest is assumed. The Ten Views provide a framework for what complete solution documentation looks like: Current State, Domain, Requirements, Customer, Information, Organizational, Process, System, Interaction, and Operational.

Picture this: You're in a product planning meeting, and someone reads out a user story: 'As a user, I want to receive email notifications so that I stay informed about updates.' Everyone nods. It sounds reasonable. But here's the problem—who actually wants this feature, and why? As an IT architect, I've seen teams build perfectly functional systems that nobody uses because they solved the stated problem instead of the real problem. This is where stakeholder stories become transformative, forcing teams to ask the right question: What outcome are we trying to achieve, and which stakeholders actually care about it?

This strategic guide helps technology leaders navigate the complex landscape of web rendering approaches—from CSR to SSR, SSG, and ISR—with a decision framework that aligns technical choices with business requirements, performance metrics, and SEO considerations to optimize both user experience and operational efficiency.

Enterprises function as systems where intentional design of operating models, interfaces, and feedback loops can dramatically reduce coordination overhead, accelerate decision-making, and create sustainable competitive advantage.