I have this idea that tooling that turns specs into documentation (like Swagger or JavaDoc or whatever) should keep a giant list of apologetic modifiers and prepend them to the front of every paragraph or section or something.

"Unfortunately, this function takes and string and…" "Deplorably, a Segment object is used to model…" "Tragically, a responds code of 304 indicates…"

Bonus points if it sticks, "We're sorry." "So sorry." "We'll try to be better in the future." "We're trying to fix it." and the like at the end.

In looking at the API documentation that my team's been writing recently for inspiration on the kinds of sentences shit starts with I was reminded: Swagger *requires* you to put a version number for your API in there. But we don't, uh, really believe in versioning APIs on my team (I guess @ me if you want). So we put 🏋🏻‍♀️ as the version number and I forgot and then was delighted to discover this again just now.


Oh. Uh. Context: Weight lifting is relevant to the software in question.

Sign in to participate in the conversation

cybrespace: the social hub of the information superhighway

jack in to the mastodon fediverse today and surf the dataflow through our cybrepunk, slightly glitchy web portal