Documentation, Hell, and Other Dark Places

It's very tempting to say that all documentation sucks, but as a developer I get that writing documentation isn't the most glorious thing in the world. But as someone who often didn't write the code, documentation is a vital means of communication. And since most programmers suck at communication, it can sometimes be an obstacle to understanding.

README is one sentence. Not a good sign.

As a programmer, the primary focus is on the functionality of a piece of code. Does the code bring you from logical Point A to logical Point B without any logical mistakes in between? If you look at this piece of functionality as a black box, we're looking to make sure that the thing that goes in produces the result we expect when something comes out or happens as a result of the execution of the code.

Programmers are pretty good at this level of thinking because the results for the most part are pretty binary. The feature, function, or piece of functionality either works or doesn't work.

But then we get to documentation and that binary result tends to get a lot more blurrier. Communication is semantic and interpretation and understanding vary from person to person. Some folks need more context than other folks. Some folks need different context than other folks due to their background or familiarity with certain concepts, designs, architectures, and languages. There's a lot to consider and lot of potential areas where documentation doesn't complete the bridge with either other developers or external users.

But the biggest problems boil down to the following two things:

1. The developer of the code already knows how it works sans documentation
2. The developer of the code would rather write code than technical documentation

So often developers writing documentation will often write documentation in such a way where certain pieces of context are missing simply because they make assumptions when they are writing. They either assume that future developers / users either have enough experience to fill in the blank or they will overlook the information because it makes sense in their head.

Then there's that creeping feeling of laziness and the temptation of new coding challenges on the horizon that documentation is written to mark the checkbox rather than to educate and inform new users.

Thus, we have that wonderful learning curve that new projects impose on developers simply because documentation wasn't done carefully with the end user or future contributor in mind. A lot of times documentation is an afterthought. Especially when deadlines are tight and there's a lot of pressure to push out functionality regardless of the quality and accessibility of the code.

So I have been looking at a new project for the past few weeks for the project I'm working on and boy does the documentation have some issues.

Often code that is overly complex and unorganized is called spaghetti code in reference to the pasta which is often intertwined and tangled up. Well, this codebase had spaghetti documentation. The documentation was all over the place. Literally.

The project was split over several repositories with each having it own piece of documentation and you could tell there was a clear lack of coordination between the groups working on the different codebases. Some documentation formatted in a particular manner would be formatted in a completely different style sometimes in a completely different location. All repositories had a doc folder. They all found creative ways to use it differently.

I think my favorite part was the documentation that referred to documentation that no longer existed. It wasn't one case either. In fact, many repositories referred to the same document. And it simply didn't exist in the current codebase.

But I was able to track down two copies of the document.

The first one was found through Googling the document name and find a version of the document from 2010. The project has changed significantly since then and is still being worked with and being worked on.

The second one was found by looking at a old tag of a prior release from 2016 and finding a newer version of the document there. Still a few years old, but a lot better than a document that's nearly a decade old.

We were able to contact one of the folks leading the project and were told that the document was removed as it confused more developers than helped them. Which I guess is a good thing except for the fact that multiple active repositories are still leading developers towards a document that was removed from them on the basis of helping them. Definitely, a lack of coordination on the documentation front.

At least people have the code to reference when documentation fails them, although I'm seen a lot of junior developers and interns quit when they reach this point as reading C code they have little experience with isn't that appealing to them. While digging into someone else's code and strangling the meaning out of it can be satisfying, it can take multiple long rounds of scribbling notes and are staring past your computer screen into an alternate dimension. You end up wasting a lot of time trying to figure out what the original creator was thinking when they made their design choices.

To conclude, documentation is very hard to write well. It is very hard to find good documentation in the wild. A lot of times you run into documentation that sucks. Maybe because the developer is lazy or maybe because the developer thinks he is better than you and code is documentation (ala Dan Larimer). In either case, sometimes you simply have to grind it out.

For those that do spend time writing good documentation and valuing its importance, thank you. Because going down code rabbit holes is a waste of time. Reading spaghetti documentation is a waste of time. Reading outdated documentation that no longer applies is a waste of time. Reading documentation that is simply wrong is a waste of time.

Remember that you have an audience when you write code. Whether it's your future self or that junior developer that is going to maintain your codebase in ten years. Don't screw that guy. People appreciate it when you put in the effort to help them. Even when it is writing a boring ass document about stuff you already know how to do.