documentation and its role in open projects

Mel was musing on documentation in open projects recently.

In our recent code sprint on the Transterpreter project, we realized that for years we have had far too little documentation. Specifically, we’ve been lacking documentation on not just one front, but two.

First, we’ve lacked developer documentation. That didn’t change during our sprint. Someday, but not during this sprint.

200907181216.jpg

Instead, we focused on a new (user-centered) platform and end-user documentation. Given that we are working on a language and a runtime for that language, it becomes difficult to document things for people. “I downloaded it… now what do I do?!” Invariably, we say “write some programs!” That’s… less than ideal. We realized that if we want more people to explore parallel programming for embedded systems, we’re going to have to provide an easy path for engaged beginners to dive in and be successful from the start.

So, we brought our language and runtime to the Arduino. (There’s some cool videos over on the Transterpreter blog; check it out.)

200907181202.jpg

The Arduino is a piece of “open hardware,” meaning the design of the device is free and open. It is powered by the Atmel Atmega328, a 16MHz processor with 32K of flash and 2K of RAM. To many people, those are small numbers, but to us, they’re enough to write interesting parallel programs for controlling embedded microcontroller projects.

We have drafted the first 50 pages of a book that supports programming these affordable ($25 or less), open devices in one of the few parallel programming languages around. Our support library is called Plumbing, and we are excited about completing the first ten chapters and sharing them with a group of “alpha testers” who can help make sure our writing is appropriate for our target audience.

Who is our target audience? We have chosen the Student Artist as our target persona for the book. This is a notional college-age student who is studying art, has no significant programming experience, but wants to add interactivity and computation to their work. They don’t want to learn to program (per se), but instead want to achieve some end: a piece of art, an installation, or similar. The electronics and programming component is fascinating to them (and perhaps a touch daunting), but they’re willing and ready to learn what is necessary to make their art as successful as possible.

This persona, we believe, overlaps a great deal with the MAKE community, and even with many students of engineering and computing. However, we have explicitly forced ourselves to consider a target audience that is not studying programming. This forces us to think about what concepts we introduce when, focus on outcomes and results (as opposed to belaboring theory up-front), and do our best to support the artist/maker in fun and thought-provoking explorations from the start.

If you are interested in being part of the group who gets a look at the book early, please either drop me an email (matt at transterpreter dot org) or leave a note with contact information in the comments (a URL to your contact info, an email address, etc.). We’ll be finishing the drafting and revising that material over the coming weeks, and hope to have an initial release of the software (a simple IDE with Arduino support built-in) soon.

20090718 | | Tags: , , , , , | 1 Comment »

collaboration vs. competition (or "zero-sum education")

Commenting on my previous post, Mel points out something rather critical:

I was grinning when I read “Those other students are the competition.” Are we, really? How does it change things if you say instead “those other students are our future partners, and we’ve got to step up our game in order to be able to really tag-team with them”? Perhaps this is my conflict-aversion tendencies cropping up, but I’ve been far more motivated to do awesome things by “I want to be worthy to hang out with people I think are super-cool” than “I will beat X or he/she will beat me.”

I think Mel is exactly right. The traditional view is to say “There is limited resource, and better I have it than my competitors.” A collaborative world-view dictates that I instead say “Value is increased if I am the equal of my collaborators.” At the root of both is the notion of bettering oneself; in the case of the latter, it reinforces the fact that bettering yourself is not a zero-sum game.

And, a digression…

Put simply, a “zero-sum” game is one where every point I score means a loss for my opponent. Recently, I heard David Brin talk about this kind of world-view in terms of a simple question:

You may have one wish, and it will be visited double upon your worst enemy.

Someone who believes in positive-sum games (where things that benefit me benefit everyone, and visa-versa) would wish for whatever they want, knowing their enemy will receive twice as much. “I wish for enlightenment” is an example of a positivist wish that does no harm to either party. A zero-sum wish is harder to formulate—one that benefits me but benefits my enemy might be “I wish we had twins.” While I would have twins, my enemy would have quadruplets—a clear strain on their resources without explicitly being a bad thing. If I wanted to make a negative-sum wish, I might say “I wish I only had one eye.” Clearly, when visited double on your enemy, this wish is truly dire.

So, as Mel points out, putting educational outcomes in competitive, or zero-sum terms, is perhaps the wrong message to be broadcasting to our students. In fact, it is almost certainly the wrong message. Our students should be learning that they can learn from each-other, and that their apparent competition are actually/also future colleagues. Therefore, their excellence does improve their chances of getting a job/getting into grad school/etc., but bettering themselves also means that they are better positioned to collaborate with awesome people Out There that they haven’t met yet.

I may update the PDF to reflect this thinking, but I’ll do it as a footnote or appendix; I want the original text to stand to make clear how deeply engrained this kind of zero-sum thinking permeates our views regarding education. Put simply, we live in a country dominated by zero-sum education when it should be positive-sum education.

20090704 | | Tags: , | 2 Comments »
Newer Entries »