Human-Scale Software

I recently posted on Mastodon:

1. I’m going to write another tech book.
2. If I do, it will be about evidence-based software engineering and/or how big tech companies operate like drug cartels.
3. But I’m still thinking about “Human-Scale Software: A Guide for the 99.9% of Developers Who Don’t Need Scalability”

So what would I use for #3?

1. SQLite for storage. (DuckDB is cool, but I’m being deliberately conservative in my choices.)

2. I wouldn’t use an object-relational mapper: I’ve used SQLAlchemy for years, but I think embedded SQL is easier to debug than an ORM for small-to-medium use cases.

3. Bottle on the back end because it has stayed small while Flask keeps growing. Note that I wouldn’t use type hints in the Python code: if I wanted to write Java, I’d write Java.

4. Ibis templates because they’re simpler than Jinja. (See also this post.)

5. mamba, ruff, and uv for Python tooling.

6. Alpine.js as a front-end framework because htmx feels a bit left-field and React and Vue seem bent on cosplaying Enterprise Java.

7. npm, Vite, and StandardJS for JavaScript tooling.

8. Mantine for the UI, though I could be persuaded to stick to Bootstrap.

9. Pa11y for accessibility testing (because the standalone version of WebAIM WAVE costs US$4000/year).

10. Netlify for deployment.

This list deliberately isn’t an entirely new stack, but it’s also not entirely conservative. I know it should include a security auditing tool to sit beside Pa11y, but while I’ve watched people use Snyk I don’t have any experience with it or alternatives.

So much for tools: what would I teach? My learner persona is:

1. Carter has a BSc in bioinformatics and now works as a data scientist for a mid-sized therapeutics company.
2. They know Python well enough to analyze data for their colleagues and build dashboards using Dash, but only ever did a couple of assignments using JavaScript.
3. Carter wants to build something to replace their company’s aging PHP-based record keeping tools.
4. Carter has an idiopathic tremor that sometimes makes fine motor control difficult. As a result, they find many websites awkward or impossible to use and strongly prefer typing to using a mouse or a touch screen,

1. The motivating example would be a laboratory information management system (LIMS) designed to handle field samples and laboratory experiments. Luckily, I already have a synthetic data generator for this.

2. Database schema design: I’d start with something simple and extend it chapter by chapter.

3. …which means the list above should have included a database migration tool like Sqitch.

4. Building a command-line user interface (CLUI) for administration, batch operations, and testing. (Crap, that means adding pytest and Click to the list of tools.)

5. Authentication: it’s straightforward to add this to the CLUI, but will require something like Flask-Login for the web UI. I don’t know of a framework-agnostic alternative, so I might have to revisit my decision to use Bottle.

6. Routing URLs to handler functions (and redirecting when authentication is needed).

7. Permissions, which means user roles. Again, Flask-User does this and I don’t know of a framework-agnostic alternative, so yeah, Flask…

8. Generating pages from templates and form handling. I hope we’ve all outgrown single-page applications, so site architecture design as a complement to schema design will need to be here.

9. Paging for displaying large data sets and plotting for displaying data graphically.

10. Responsive web design because most a lot of people use their phones more than their laptops (particularly when they’re in the field).

11. Accessibility because I’d be ashamed not to and because I’m not getting any younger.

12. Security is a hard one. CORS, CSRF, SQL injection, authentication, site certificates, and password management are all must-haves, but as Mike Hoye has observed, what we really need to teach people is things like, “How to build websites that can’t be exploited by abusive domestic partners.” I really don’t know what I could do here that wouldn’t require a second book; I would try crowdsourcing it like The Architecture of Open Source Applications, but that didn’t go anywhere the last time I tried it.

This book will probably never happen, but probably isn’t the same as definitely. If you think of anything else that ought to be included, please let me know.

Later:

• Irving Reid pointed out that running the application is as important as building it, and suggested the lessons should include creating and restoring backups, deploying updates, and observability (which involves more than creating log messages that are findable, comprehensible, and informative, but that would be a good start).

• Someone else (name unknown) felt that dependency maintenance should be on the list as well, i.e., that there should be a lesson about vulnerability scans and automating checks for dependency updates.

• Someone else (name also unknown) suggested that there ought to be a lesson on debugging full-stack applications, and that the lessons should show how to create good pull requests and how to review them. I strongly agree, but teaching verbs is a lot harder than teaching nouns, and this is already far too ambitious for something that would already take a year of unpaid work.