Bestiary: On Doc Types and Other Animals
Of documentation many are the kinds throughout the web—unnumbered, since no writer can count their multitudes, nor rightly learn the ways of their wild nature; wide they roam, these patterns, as far as Internet sets. Let me, o reader, speak of these bewitching creatures, for in the end all content types are chimeras, and those who work to reduce their number are doomed to fail…
We have heard of a fast fiend, the Releasaurius, or changeling, ceaselessly roaming through the digital wastes. It contains the latest words abouts products, shedding its monstruous skin when a release sets its course. It explains little, yet attracts many eyes. Of meagre meat, it provides little nourishment to the learner. [Release notes]
The weary-hearted writers who sail on merchant ships know of the Realisticasius, which disguises itself as a tutorial. Fettered with experience, this worm entrances rich customers with the perfume of real business cases, departing the shores of theory and abstraction. Hideous but cunning, it increases sales. [Scenarios]
Straight from the dusky caves of practice emerge the Examplanatii, detailed in their manners and speech. Upon sighting these crafty fiends, dispirited coders are flushed with joy, for they understand now what they couldn’t grasp before, not through tutorials nor reference. Short-lived as they may be, they serve a greater purpose. [Examples]
The Solutionarius is called so on account of its swift run, as Persians and Greeks named him the Troubleshooter. Though they may break everything in their path, their marvelous velocity helps the user in vanquishing dangers and technical issues. Bound to the yoke of dire problems, they falter not in their resolve to help. [Troubleshooting]
I now shall spur again my wit, and tell you of the Optimarius, a most excellent type of document, proud and bright. It flies majestically, awarding words of wisdom to the lost and the confused. It picks its preys wisely, and is immediately responsive to any plans which a user enacts. [Best practices]
The Interfacilus rides the beautiful UX, which dwells among users and makes a great show of itself. Gently nudging its mount, the interfacilus goes wherever it will. The teaching imparted by this swift, if opportunistic passenger, dear reader, is that few words, yet well chosen, may bring the user to its destination. [UX writing]
What you’ve just read is a satirical take on documentation frameworks and taxonomies in the form of a medieval bestiary or compendium of beasts. The introduction paraphrases the English translation of the Physiologus, a bestiary written in Alexandria in 140 B.C. All the illustrations were generated using DALL-E; the file names retain the full prompts provided to OpenAI. I wrote the text myself, by the way, so, no, OpenAI didn’t do it. It could not.