If there is one thing that analytics reveal about technical writing, it’s that developers want code, not concepts. Programmers have a problem, and they want the solution to that problem now, not below the fold after a multi-thousand-word discourse. (Umm… The answer to this column is C = 5/9 * (F – 32).)
When it comes to code, though, there is great truth in the old saying: “Give a man a fish, and you feed him for a day; show him how to catch fish, and you feed him for a lifetime.” Do you have some library or framework for which, when people come to you with questions, you say “Before I answer that, the thing is…”? Of course you do.
In iOS programming, where I’ve been spending much time lately, there are a handful of idioms (such as Apple’s version of Model-View-Controller, the delegate-object model, and their API naming standards) that provide, if not mastery, at least rapid navigation across the SDK. Similarly, with Mike Bostock’s brilliant D3 library, one can stumble along with any number of samples, but until one learns the library’s data-handling model, stumble along is exactly what one will do.
(Related: Another way to learn how to code)
Not every recurring problem has this characteristic. Regular expressions with capture groups and replacement? I’m not embarrassed to use an interactive tool to build them. Debugging XSLT? Good luck! (On the other hand, complex XSLT can actually be built using a consistent set of principles, but actually encountering such a codebase is as rare as meeting a unicorn.)
This vicious cycle is an unfortunate consequence of our evolution toward a world in which systems are more mashed-up than architected: as the odds of starting from well-architected code decrease, so too does it become less likely to see the patterns of proper use, and the more likely it is that one contributes a non-idiomatic patch, perpetuating the problem.
But I remain utterly convinced that there is more to good code (not to mention productivity) than getting the test suite green. Whether we call them patterns or idioms or “(language)-ish,” there’s a bunch of stuff that exists at a higher abstraction level than functions and values. Such concepts have been the traditional bread and butter of technical articles, whether in print or online. But it’s clear that concept-driven Web pages are skipped over in favor of code-above-the-fold “here’s the answer, move along” pages.
Books are the natural environment for deep, context-establishing technical writing, but if you read on a tablet or computer, it’s hard to stay immersed. While paper books have the advantage in terms of immersion, they have disadvantages in terms of interactivity, weight, and, when it comes to the type of technical library a programmer should have, sheer volume.
To be sure, I agree with Steve Yegge’s tweet: “I don’t think pointy-hairs fully understand how much StackOverflow has revolutionized programming. It’s the biggest accelerator since IDEs.” StackOverflow is an amazing accomplishment that somehow manages to provide (mostly) civil, (mostly) timely and (mostly) accurate answers to questions of all technical levels, at a global scale.
What unites these observations is the Internet. We live in a marvelous world where fiddly coding problems can often be solved by the first link returned by a search query. Today’s programmers are not stymied as easily as we were in the Good Ol’ Days and, perhaps, are under pressure not to step back and contemplate the bigger picture.
But there are other times when the Internet is not available (or, at least, less convenient). Plane flights and commutes on public transportation are times when it still seems natural to take one’s time studying material. Some colleagues and I brainstormed the idea of an app that asked you “How long is your flight?” and provided you an appropriate breadth and width of papers, blog posts and videos on a topic.
This scenario, where context and reflection are luxuries snuck in during commutes and flights, may describe the general experience, but I hope that it doesn’t describe yours. I understand that developers who are stuck reward those pages that get them unstuck with a few lines of code. I believe that programming talent is more—far more—than the number of lines of code or successful compiles made during a day. I think that software gets better when they are written purposefully and I think that programmers get better when they understand, not just the how of their functions, but the why.
