Spec

Stack Considerations

The Stack area should let a non-developer understand what they are getting. The technologies below are ones a developer takes for granted, but a client hiring you may never have heard of, or may not know why they matter. Most of them are already used in your stack, and some already have how-to pages, but none has a plain-language page saying what it is and what it means for the client.

The pattern that works, from Git and Gitea, Gitea Actions and C# and .NET: say what it is in two sentences, a short glossary table, What you get (the client's benefit), How I use it, your experience with it, then links to the how-to pages.

Write these first

These are the ones a client is most likely to ask about, or most likely to be worried about without knowing to ask.

Topic Why a client cares Already covered by Suggested page
AI coding agents It is the heart of the Services pitch: one developer delivering a whole SaaS product. Clients will want to know what the agent does, what you still do (design, review, testing, decisions), and what their code and data are shown to. Without a page, the pitch is a claim with nothing behind it. Nothing How I Work with AI Agents: what they do, how every change is reviewed and tested, what data they see, and why it makes you faster rather than careless
Security basics Clients are responsible for their customers' data. HTTPS, password storage, updates and access control are what they are trusting you with. Scattered: Caddy (HTTPS), Add Login to a Blazor Server App, Secrets on a Linux Server, the bootstrap rules How Your Data Is Kept Safe: HTTPS everywhere, passwords hashed (never stored), 12-character minimum, automatic security updates, firewall, no secrets in Git, least privilege
Docker and containers Explains why hosting is cheap, why each site is isolated, and why moving to another host is easy. How-tos only: Containerize a Blazor Server App, PostgreSQL in Docker Docker and Containers: shipping containers as the metaphor, one app per container, memory limits, easy to move
Hosting and running costs Clients need to budget for after the build: server, domain, email, backups. Self-Hosting Architecture (written for developers) Hosting: What It Costs and What You Get: a VPS in plain terms, typical monthly costs, what is included, self-hosted versus cloud

Worth a page later

Topic Why a client cares Already covered by
Databases (PostgreSQL) Where their data lives, that it is theirs, and that it can be exported. PostgreSQL in Docker (how-to)
Domains and DNS Who owns the domain, what happens when moving hosts, why email depends on it. BIND9 and Terraform (technical), How Email Works
Automated testing Why bugs are caught before release; what xUnit and Playwright tests are, in plain words. Nothing (tests exist in JM.Tests)
Linux Why the server runs Linux and not Windows: cost, stability, no license fees. Linux Command Cheat Sheet (commands only)
Infrastructure as code (Terraform) The server setup is written down and repeatable, not hand-made and fragile. Install Terraform on Ubuntu, the BIND9 runbook
Caddy and HTTPS The padlock in the browser, and certificates that renew themselves. Caddy Cheat Sheet
Blazor, explained Why the site is fast and works without much JavaScript. Blazor how-tos (no "what and why" page)
Email deliverability Why their emails land in the inbox and not spam (SPF, DKIM, DMARC). How Email Works, Self-Hosted Mail on a VPS
Search engines (SEO) Being found on Google, structured data, sitemaps. README only
Accessibility Usable by everyone, and a legal requirement for many Ontario organizations (AODA). Nothing
Languages and translation What it takes to offer a site in French or Chinese, and its limits (the notice on this site). README only
Analytics and privacy What is measured about visitors, and what is not (cookies, consent). Spec Analytics
Offline support The site works without a connection. Spec Offline Support
Markdown and Obsidian Clients can edit their own content as plain text. Notes with Obsidian
Tools: JetBrains Rider, Docker Desktop Mostly invisible to clients; one short "my tools" page is enough. Nothing

Done

  • Backups and disaster recovery: Backups and Recovery (Stack, Hosting). Nightly encrypted copies pulled to the home machine with restic, kept 30 days, with a monthly restore drill and the rebuild steps. Its status line says it was written before the first run: remove that once it is running, and once the first restore drill passes.

Smaller fixes noticed along the way

  • Empty skill pages. Skill/C#.md, Skill/Blazor.md, Skill/GitHub Actions.md and others have front matter but no text. A sentence each, with a link to the matching Stack page (for example C# and .NET), would turn the skill tags into useful pages.
  • Tests in CI. Gitea Actions builds every push but does not run the test suite yet. Adding dotnet test to build.yml and preview.yml would let the page say "every change is tested automatically", which is a stronger promise to a client.
  • Ownership and handover. A short note, on the Services page or in the Stack, saying who owns the code, the domain and the data, and what a handover includes. It is often the deciding question for a client choosing a solo developer.
  • Translations. New Stack pages need French and Chinese versions, or they show the "not translated" badge on those sites.