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.mdand 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 testtobuild.ymlandpreview.ymlwould 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.