A Case for Documentation - Confession 61

2016.03.18 23:24:06

header I thought I was done typing for today after spending all day writing up the documentation for North, but I guess I was wrong. Now, there's something that I've noticed every now and again when I take a peek at some of the new projects that pop up on Quicklisp.

Every so often there's one or two libraries that sound interesting or useful to me from their description. But then when I take a look at their project page, way too frequently I have to discover that there's either no README at all, it's just a template copy, or has a single, lonely paragraph out in the cold white space in it. It's also pretty common that docstrings are either completely absent, or only partially existent. This is really sad, because there's a fair chance I would have tried the library out, or in the very least kept it in mind for when I need it later.

Now, I understand, writing documentation takes time. A lot of time. And a lot of people are simply here to get their work done quickly. That's absolutely fine by me, I'm a very impatient person myself. However, when it comes to submitting a library to Quicklisp, it seems to me that the idea behind that would be that the library might prove useful to somebody else, so that they don't have to spend their time writing the same thing again.

And this is where Common Lisp's strength of rapid prototyping becomes a severe flaw, because it pushes people to simply roll their own thing again as they can then fit it perfectly to their needs. Plus, it's probably much more fun or even quicker to do than trying to grind through someone else's undocumented code, desperately trying to figure out how to use it or make it work in the first place.

Writing documentation takes a long time in part because it's hard to formalise and ratify things to fit into text so that hopefully somebody in the world can understand what the thought process was. Now imagine trying to do exactly that, but you did not actually write any part of the code that the documentation should describe. Trying to reverse-engineer the missing documentation from the code is a huge lot harder than writing documentation itself.

As such it doesn't surprise me much to find a lot of people distraught with the current library situation in Lisp, even though over a thousand of them are now readily available by a mere command. A large part of that particular pie is definitely also attributed to the fact that it's simply hard to discover libraries that would help you solve the problem you're tackling, but I cannot imagine that the insufficient amount of –or complete lack of documentation is not also a part of what deters people and makes them think there's nothing useful around.

Obviously there is a lot of useful code around, a lot of time and talent is hidden away in all the projects that were written in CL. It's simply such a shame that a lot of it is so difficult to get a handle on. So please, I implore you, take some time out of your busy schedule and write some documentation for your library before you submit it to Quicklisp. Even just a few paragraphs with a “How To” section that explains how to get the most basic task done helps tremendously to make your library more welcoming.

But even if you don't care about anyone else and simply submit your code to Quicklisp to profit off of its ease of distribution, I still implore you to write documentation– at least for your own sake. Trying to read back into the code of a library that's even just as little as a few months old without any documentation to go by is a huge headache and time-waster. Figuring out some way to reconstruct your past self's ideas and thoughts is very difficult, no matter how much you think you know yourself.

Writing good documentation goes beyond writing a README for your project however. Good and complete documentation includes docstring coverage of all definitions in your code, including those that are not exported, it includes writing not just about the surface on how to make use of your library, but also about its inner workings, how the machinery fits together and what kind of concepts and ideas were realised to make it all work, what kind of problems it aims to solve and how. I would even go so far as to say that good documentation is also the organisation of your source files, how you divide the code and spread it over files, packages, and systems, what you name each of them, and how you reference things across them. All of these things are –if done right– a huge help for anyone that attempts to gain understanding of your code.

Such a level of documentation takes a lot of effort, consideration, and time to do. However, while I know that I too have not reached this level for all of my libraries, I find that the ones I did the most work for are also the ones that I can find bugs the fastest in and have the least trouble getting back into when trying to rework or extend them.

So, please. Please consider taking some time out of your busy schedule to write some documentation.

P.s: If you're one of the people who thinks that docstrings in the definitions are horrendously cluttering up your source code and make it hard to see the forest for the trees in there, have a look at documentation-utils which aims to make it easy to define documentation outside of the associated definition forms.

Written by shinmera