I’m delighted to announce that issue 10 of PragPub is out today, and contains an article by me, Tangled Up in Tools. For those who like nice typesetting, you can download the whole issue as a PDF, or as epub or mobi (whatever they may be).
PragPub is the monthly programming magazine published by the Pragmatic Bookshelf — that’s the publisher that brought you the definitive books on Ruby and on Rails, among much else. I like their stuff, and I am pleased to be in their magazine. Not only that, they let me illustrate the article with photos of — oh, but you’ll see for yourself when you read it.
So what is the article about? I was commissioned to write it in the wake of Whatever happened to programming? and its followup, and asked to write on related topics, so the tenor of the article will seem familiar to those of you who’ve been reading since back then. (It’s astonishing to me to think that Whatever happened was published only five weeks ago — it seems much longer.) This is a completely new article, though, sharing only the Knuth quote that kicked off the original. Rather than just whining about the state of things, I tried to finish up with two specific suggestions for making things better. (Don’t worry, though — there is plenty of whining as well.)
Those two suggestions are:
1. Better documentation of libraries, and by “better” I largely mean shorter. Documentation that tells you not just how to use the library, but why you would want to use it, what it can do for you, and when it’s appropriate. Documentation that is free of the word “Enterprise”. Most importantly, overview documents that fit on a single page of A4. (I think of Mark Ardis’s observation that “a specification that will not fit on one page of 8.5×11 inch paper cannot be understood”.)
2. Trying to reduce what I’ve called the “radius of comprehension”. It’s a property of a codebase that I defined as follows: if you are looking at a given fragment of code, how far away from that bit of the code do you need to have in your mind at that time in order to understand the fragment at hand? I think this it potentially a valuable concept (although it’s going to need a lot more thought than I’ve given it so far). In short: if I want to use a class from your library because it solves a problem for me, do I need to learn eight other classes from your library before I can do that? If so, then the RoC is too high.
Of course the article itself has a lot more to say about this concept. I’m keen to get your feedback so don’t forget to come back here to comment after you’ve read it!