(((•)))
tech.interfluidity.com
a notebook by steve randy waldman
→ See also top, archive, subscribe, drafts blog, interfluidity main
2025-11-08 ⇒

# Sysadminning in Scala, documenting in Claude

TL; DR: Me and Claude code collaborated on some documentation for my Scala sysadmin library. Is it any good? Maybe other people would use it?

***

I don't like to do anything very complicated in a shell script. It feels loosey-goosey. I don't quite know what's going to happen, how things will behave if anything goes wrong.

I love doing just about anything in Scala, a programming language as tight and neurotic as I am. When I write Scala, I feel like I have pretty complete command over what happens. I find it easy to precisely check important prerequisites and provide detailed information about whatever goes down.

So I love automating sysadmin tasks in Scala.

Sysadmin tasks are high stakes. Often you are letting some piece of code run as root on production servers, doing something that really does need to be done. So I want to write my "scripts" neurotically. I want to have pretty complete and convenient information about what goes down when they run.

A few years ago I wrote a library in Scala to structure my automation of self-reporting sysadmin tasks. I get colorful HTML e-mails when they run, with a big `SUCCEEDED` or `FAILED` in the subject line.

Like most of the software I write, I made my library available as open-source, but had little hope or expectation that anyone else would actually use it.

I certainly didn't put in the time to write documentation that would make it easy for other people to use it!

This week I was messing with the library a bit, and it occurred to me that if I didn't have time to write documentation, maybe Claude would. So I asked Claude code to do just that.

I started with a pretty dumb prompt:

    > Could you write a comprehensive piece of documentation, in markdown, for developers interested in using TaskRunner?

Like so much in LLM-land, the result was incredibly impressive but also deflating. Claude code seemed to understand my code very well, and did a good job of explaining it. But there were errors, often small surprising things. Overall, I felt like Claude got all the hard-stuff right, but occasionally whiffed trivialities. Discerning and addressing those small mistakes meant the exercise was somewhat time-consuming.

It was not, to be clear, nearly as time-consuming or stressful as writing documentation by hand would have been. But we did go around with a bunch of revisions, and ultimately I saved less time than I'd initially imagined that I would.

At first I played manager to Claude the copy writer. I offered my observations and corrections in dialogue. Claude dutifully updated the text and fixed the errors.

(At one point, Claude was so attentive to my feedback that it offered to misstate the API in order to conform to my simplifying suggestion! I said no to that change.)

Eventually I went in and did some hand-editing.

The documentation that Claude produced is more long-winded than what I'd have written. But it is also more comprehensive.

Looking at Claude's examples, and how cumbersome they were, inspired me to change the API, significantly and for the better. That process seems like a contribution, even if you can't see it in the final product. (Claude cheerfully revised the code to the new, less cumbersome API, so that's all you see.)

Claude was quite ambitious. It created a vast "Complete Examples" section, just inventing common sysadmin tasks and writing scripts for them. I took that out because they were scripts I couldn't run to verify — they relied on file systems and resources that weren't mine — and just inspecting them I pretty quickly found some problems and bugs. I'd rather have fewer examples than mistaken examples.

Claude agreed removing the section was for the best. But Claude pretty much always agrees.

In any case, while I'm vain enough to think that if I'd written the documentation from scratch it would be better, I think what our collaboration produced is pretty good.

And I would not have taken the time to write the documentation from scratch!

It strikes me that a relatively good outcome for LLM usage would be that, rather than replacing labor, we just do more of things that might prove useful and valuable, but that would previously have been too time-consuming and speculative to justify the opportunity cost.

I'd love it if other people found my library useful. But I think the likelihood that even comprehensive developer docs will bring interest to this project is pretty low. Given that, without Claude, I just wouldn't have devoted the time.

But with Claude, (co)authoring decent if not fabulous documentation is faster and easier than it used to be. So maybe I'll document more of my projects this way. The likelihood that other people find something in my portfolio worth using, that library if not this one, might increase.

It wouldn't be the singularity, but I'd score it a win.

Anyway, here are pointers to the library and its Claude co-authored documentation, if you are interested.

← Zip-A-Dee-Doo-Dah
↑↑↑