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.

Tagged #knowledge-management, #technical-writing, #communication, #programming, #documentation.

Similar posts

More by Jim

Want to build a fantastic product using LLMs? I work at Granola where we're building the future IDE for knowledge work. Come and work with us! Read more or get in touch!

This page copyright James Fisher 2014. Content is not associated with my employer. Found an error? Edit this page.