Technical Manual Regression Testing

If you hate GenAI, you probably want to skip this episode, though I would assume anyone reading my blog should already know what I do.

Sharpee has been stable-ish for a few months. I bumped it to 1.0 and started revising the repository documentation. It occurred to me to take a swipe at a full technical manual. I collaborated with Claude on what that might look like and the one big tutorial we have, Family Zoo, is the perfect "spine" for such a book.

So we started with an outline, then wrote out each chapter, and I've been editing everything word for word as we go. I took the first completed book to a docker container and a naive Claude (I have a lot of infra for my daily Claude usage so it knows a lot about me and Sharpee). This naive version wouldn't have any of that information. The idea was to turn on Claude, copy the book over, and let it "execute" the book with explicit instructions not to solve problems outside of copying the example code, reading the text, and following it without exception.

This ended up being way more useful than I expected. Not only will I have a completed, edited, and tested Sharpee Developer Manual, but it has also acted as completely user-oriented regression test of the platform. And we found things. Not a lot, but we found things.

• I split out the npx functionality from @Sharpee/Sharpee and created two build tools. The external tool is @Sharpee/devkit and the internal tool is ./repokit. Authors would run npm -g install @sharpee/devkit and get local sharpee commands for init, build, add browser.
• One of the formatters was off {items:count} and missing article integration.
• The list formatter was incomplete and also missing article integration. That needed a complete rewrite. Oxford commas are optional, but available.
• Some of the edge cases for Channel IO got lost in its implementation and those are now fixed.
• Extracted the themes into its own package so authors can easily override/add their own theme from a front-end developer perspective. The default theme is the DOS Infocom classic.
• There is a new @sharpee/runtime package that bridges between Sharpee and the target client (CLI, browser, desktop).

I'm still editing the book. Claude writes "okay" for a technical manual, but it uses Yoda-like phrasing, em-dashes like they're candy, and loses its audience sometimes. It would have been passable without the editing, but I'd rather spend the time shoring up all of those weaknesses before "publishing" it. We're currently at 302 pages (with TOC and Index).

It will be available as ePub, html, and pdf and the source files will be in the repo.