500 Words — Day Twenty-Two: Documentation
Yeah, I’m actually writing about documentation. There’s nothing like technical writing that keeps the world going round. The harsh truth is that even though just about everyone hates writing documentation (especially the programmers like me), it is absolutely necessary in order to maintain and grow a product beyond its initial creator.
Documentation is used to communicate data about an object or a process so that the person who is reading or looking at the document is more informed about that object or process. The instruction manual that you throw into the garbage bin without reading it is documentation. A spreadsheet showing accounts and their balances is documentation. A stop sign, if you really think about it, is documentation. While people ignore a lot of documentation, when you run into a problem, documentation is a lot of times really helpful in getting a better picture of how things work.
As someone in a technical profession, good documentation is vital. Without good documentation, you are stuck in the unenviable position of having to reverse engineer the intentions of the creator of the product you are trying to understand, fix, or use. Reverse engineering is essentially educated guessing which depending on the problem can take a few hours of tinkering up to the heat death of the universe to solve. As someone who is busy and doesn’t have the heat death of the universe amount of time to spend, documentation that describes proper usage and gives examples of that usage can go a long way in eliminating the need to guess a lot. The nice thing about an example is that if the example doesn’t work, you can quickly uncover that the product that you are dealing with is either broken or poorly designed. Because sometimes it is your own stupidity that the thing is not working correctly. Sometimes you probably should have kept the instructions you threw in the garbage bin because you actually don’t know how to put this piece of furniture together.
But maybe everything is working well. If you design something that always works, then documentation may seem like it is a nice thing to have. However, if there is even the slimmest chance that the product needs to be changed or someone else may be working on it, then documentation serves as a bridge from now to that future work so that future you or that future engineer doesn’t have to figure things out by digging around and reverse engineering the old product. Sure, you would expect them to have the ability to do such work, but that is time spent trying to recreate the mental model that created the product in the first place rather than just handing them a mental model on a piece of paper or some word document. By providing documentation, more time is spent expanding upon the idea rather than figuring out how the idea works and why the idea was implemented in the way that it was.
So if you ever happen to be in the situation where writing a really boring document explaining how things work could potentially save someone’s time, do it. That person will appreciate it down the line. The world will be a much easier place to maintain and to grow. The alternative is a world where we build some beautiful mess that works via some streak of creative genius but forget to write down how it was all put together and now have to wait for another streak of genius just to get us back to where we were before.
