Open Source Documentation, and What I Learned from College

In Jon Udell’s latest blog post speaks about the importance of motivation and context when learners approach topics above their current ability to understand. The example of patients reading current medical research papers online is particularly apt, and one that I know firsthand due to shoulder injuries, and some time spent as a research assistant in my youth.

I completely agree that the open-source world provides a humongous amount of context that I’ve never seen matched by any closed information system. Open source software is typically launched these days with a website, embedded documentation, a wiki, bugtracker, and a discussion list of some sort, and the ensuing conversations around any piece of useful software provide a boon that beats any thick manual hands-down. Software vendors are simply too close to the problem to step back and provide documentation from a learner’s perspective, whereas the adopters, users, and hackers that run open-source software for the first time actively participate in an instant feedback loop where they may share their own experiences with a technology for the benefit of all its other users.

This is something that is typically lost on many, in part due to historically poor presentation and design of feedback systems – when all we had was usenet, obtaining documentation was substantially more frustrating. GNU Mailman systems without a searchable web interface come to mind. Google groups provided a better alternative for a while. Now that we have wikis and bugtrackers that look nice (see the Trac project), the feedback loop presents context in a more digestible way, and drives the creation of more of it.

The other part of the equation of learning above your capacity is motivation, and Jon addresses that both with the medical example, and also with some hiring criteria from Ray Cote.

Ray told me that he’s not looking for people who “know” one or another language or framework, but rather for those who can motivate themselves to rapidly acquire these and other contexts as needed.

This is a great hiring criterion for programmers. Is it difficult to ascertain this during interviews? Shouldn’t be – ask them about projects they do outside of work. Typically, talented programmers who can create motivation for themselves do so in the form of projects. I learned to do this during college, a time when most programmers are required to constantly reinvent the wheel in the hopes of ingraining some repetitive familiarity with the mechanics of programming. As a result, the code I produced immediately after college was absolute rubbish. I don’t deny that the reptition was useful, but it produced no fundamental or sophisticated understanding of programming as a means to an end. Instead, what I learned was generally syntax, familiarity with algorithms, and what can be accomplished through programming. In contrast, my humanities education in the Thematic Option program at USC challenged me in the ways I needed.

Post-college, I did not believe that I liked programming, but i’d take it as a job until I figured out something I preferred, because it paid well. I entered the programmer’s employment market of 2002.

A funny thing happened during the 5 months I was unemployed, though. Left to my own devices, I began to build software to itch my own scratches, employing techniques and methods I had learned from the open source web. Eventually, that time I spent in those 5 months resulted in my employment working for Andy Baio, the founder of Although I am but a tyro in the art of programming, I can confidently say that my code has improved since 2002 almost solely due to the context provided by the open source world, directly or indirectly. 🙂

To summarize, college will not give you any motivation for learning – that has to come from the needs and wants that you have or observe. The context to look for is available, growing, and alive in the open source world. The fact is, as Jon observes, that the network effect surrounding open source documentation is alive and well in other fields where the democratization of information is becoming widespread, and we can hope that it might lead to highly motivated individuals to take on challenges that might originally seem beyond their abilities.

Leave a Reply

Your email address will not be published. Required fields are marked *