Documentation black holes: things we write that don’t get read

Nearly all the software I’ve ever contributed to has crappy or non-existent documentation. The software your company produces is the same. But, strangely, this is not for lack of writing. I probably write significantly more English about each feature than I write code to implement it. So where does all that writing go?

It goes into a documentation black hole. This is a place for written things that will never get read; a place where words go to die. There are many kinds of documentation black holes:

What isn’t a documentation black hole? A documentation white hole, stupid! What documentation does get read? Answering that isn’t so difficult: just consider what kinds of things you read about the software that you use. Things that I read include:

In science (fiction), things that descend into black holes can be ejected from a white hole somewhere else. Can we make that happen here? Can we link up our documentation black holes to white holes? How can we get more of the words we write into a position to be read? Here are some pieces of advice for that.

That’s all for now. Get out there and write things that people will read!

This article was previously published here.

I just released Vidrio, a free app for macOS and Windows to make your screen-sharing awesomely holographic. Vidrio shows your webcam video on your screen, just like a mirror. Then you just share or record your screen with Zoom, QuickTime, or any other app. Vidrio makes your presentations effortlessly engaging, showing your gestures, gazes, and expressions. #1 on Product Hunt. Available for macOS and Windows.

With Vidrio

With generic competitor

More by Jim

Tagged #programming, #documentation. All content copyright James Fisher 2014. This post is not associated with my employer. Found an error? Edit this page.