A taxonomy of old haunted manuals

Haunted manuals are a lot like haunted houses. Some of them are old and got that way because something horrible happened in the past and it’s marked them. Some got that way because something wonderful happened there and they have been neglected. Some are abandoned. Some still have people living in them. And some were born haunted.

Did I lose you? If so, I might suggest going back to part 1, where I introduced the idea of haunted manuals and promised examples. This is the post with the examples. I spent too long defining the curse of knowledge and hauntology last time to get to them. I should add that pretty much all of my examples are online documentation. It’s what I’ve known. I kind of suspect that print manuals are less likely to become haunted in many of the ways I’ve outlined, but then again, maybe only the unhaunted manuals survive to be sold in ephemera shops to weirdo collectors.

I’m going to be like Kant here, or maybe de Sade, and organize the types of haunted manuals into categories and subcategories, even though I’m making it all up, so it seems very rational.

Old haunted manuals #

I think it's more intuitive to imagine that old things become haunted with time, so I'll start my taxonomy here. Further, they can be divided into abandoned and inhabited.

Abandoned old haunted manuals #

Once they were loved, alive, maintained. Now, bitrot has taken hold: dead links and broken images. Or, the product is gone but someone is still paying the web hosting bill, and you can download a PDF. It looks nice, but the product has gone on an incredible journey into the sunset. It's dead, and yet it lingers.

Or it could be a README for a long-abandoned GitHub, project, instructing you to set up dependencies years out of date themselves. Hell, whole repos could be haunted, accumulating progressively more desultory bug reports and ignored pull requests.

Sometimes, in the early stages, these don't feel that different from a maintained (but haunted) manual. I think readers can sense it, though. It makes them worried about the project or product if the docs start drifting into bitrot. They feel the ghostly tendrils in the broken links.

Inhabited old haunted manuals #

If you are working on any kind of online manual that's been around for more than say, 5 years, it's almost guaranteed to be haunted. At the very least, it has haunted parts.

That's right, I'm saying you probably live in a haunted manual. (If "you" are a tech writer and if "live" means work on.) It might be just a little bit haunted, or you might be living in the documentation equivalent of Grey Gardens (1975), ignoring whole sections of weird old stuff that rots about you, half-abandoned. You mean well and you're trying your best, but now there's just the two of you left where there used to be a whole staff, and the racoons, of course.

Just to give some more examples, of this, probably most common type of haunted manual, it might be

• haunted by now-resolved long running bugs
• haunted by previous versions of the manual
• haunted by a previous style guide
• haunted by a previous version of the software
• haunted by laid off coworkers
• haunted by by CMS migrations

Internal documentation is, in my experience, even more prone to going Grey Gardens on you, because no one ever quite has the time to clean it up. It's not embarrassing you to clients and you can just tell new hires about the outdated parts. Right? Except what about when everyone who knew which parts were still good leaves, and some new person discovers the strange old relic with no one to warn them and they bring down production because the docs didn't specify you had to warm the cache and how to do that? (Perhaps at this point we enter the realm of haunted and cursed.)

Even when you try to exorcise the ghosts of the past, the absences leave a kind of scar that a sensitive reader will spot. Even when you throw it all out and write something new, thinking you'll have a fresh start, you can't escape it. In fact, that's the next section.

Next time: new haunted manuals #

This is where hauntology comes in. Once again, it is past 11, which is past my bedtime, and so I leave you here, dear reader, with promises of the hauntology of manuals to come.

The haunted manuals series #

1. Haunted manuals: You've heard of the curse of knowledge, but could your manual be haunted as well?
2. Elegant diagrams (not haunted): Haunted manuals, part 2, being a digression through circuit diagrams
3. A taxonomy of old haunted manuals: Your manual is haunted. But how, exactly? (Haunted manuals part 3) < You are here

About the images #

The header image is a close crop of an ink on paper drawing of an angular tree-like diagram branching out from a central circle that I drew it in 2020.

I made the spooky papercraft house as a Halloween decoration many, many years ago. Then I didn't take it down for months until the construction paper faded to a ghost of its former color. The only picture of it I could find is the one I uploaded to be my GitHub profile, so that's what I've used here. My GitHub repo is definitely haunted.