🎵 The song for this post is Street Life, by Randy Crawford. 🎵
It was the lack of available docs that prevented me from running COBOL ON COGS
I like documentation too! It’s often a low bar to put some effort into them and get long-term external benefits from, and I also find it internally motivating because it looks cool once you’ve written them.
The documentation project I’m most proud of is a build-time tool I wrote called Harbor (it’s where the docks come from) that scans my Java web application server’s method signatures and Javadoc comments to automatically produce API documentation web pages with comments, examples, and descriptions of each method, input, output, and class, as well as live test drive forms to fill in arguments, see the request, send it, and see the response. The output is packaged up as HTML into the web application and served alongside the API itself. This way, any time you change an application resource class, the docs are guaranteed to be up to date on the server you’re accessing, and the programmatic data (URLs, parameter names, types, HTTP verbs) are impossible to mess up.
It also autogenerates a Java API client for the server, like SOAP without all the damn SOAP. I’d like to add support for more languages if possible, if I could find alternatives to JavaPoet for other languages.
I was inspired by the best parts of API documentation sites from Google, Twitter, GitHub, and Flickr, in terms of the types of information they provided and how they organized and exposed them. I was also inspired by Restdown, which I used for a smaller project and wanted to take further. This was in the days back when all the other documentation generation tools like Swagger either didn’t exist or were inflexible tools that didn’t do what I want and created very ugly, uncustomizable pages (probably still true today).
I tried GitBook over the holidays when I was reverse-engineering the Tesla Owner API, since that’s what the existing upstream doc project was using. GitBook sucks. It’s like trying to draw flowcharts in Microsoft Paint. Simple reordering operations are impossible. Multiple examples for one method are impossible. The reliance on a Git-based workflow doesn’t sync properly and is astoundingly confusing, like every other Git-based workflow I’ve ever had the displeasure of using. Copy and paste is broken. Drag and drop is broken. You always end up accidentally duplicating a method. Adding scripting is impossible. Diffs are unreadable and drafts are mystifying, and I’ve been using Git professionally for almost a decade.
Docs, especially when the audience is broad, are a never-ending challenge, but making them better is always rewarding to me and can be a fun technical adventure in itself.