One of the goals of this project is to blur the line between developer and expert end-user. To that end I'd like to invite everyone with an interest in the project to write your own addins, or otherwise pitch in and help with the development efforts.

This requires two things:

1. An understanding of how Ode works

2. Some knowledge of the Perl language and general programming concepts

3. An understanding of how Ode works

I will do everything I can to help you understand how Ode works. I consider documentation to be a fundamental aspect of this project - every bit as important as the code itself. I will not slough off the documentation effort, both as a matter of principle and because I believe that emphasizing documentation is the single best way to nurture the long term success of the project and grow a healthy and vibrant community.

As evidence of that commitment, consider the annotated version of the source included with the project, which is a line by line running commentary of the script discussing not only what the code is doing but why. As I update Ode, I start with the annotated version, and then generate the leaner unannotated version from it. So, I can say confidently that every subsequent release will include its own annotated source file.

It's important to understand that though the annotated source code does contain the source, the emphasis here is on the annotations and not the code. As should be plainly obvious, the annotations are a great deal longer than the source code itself. I hope it is just as obvious that this work represents a very significant amount of time and effort. Please don't make the mistake of disregarding this as nothing but code. It's an attempt at a narrative approach to the task of developing the software. As such, it is an integral aspect of this project.

The annotated source is just the beginning. There will also be diagrams describing the execution flow of the script, addin interface specifications, sample themes and wireframes, and more. I also plan on having the usual sorts of support resources (including possibly a forum, mailing list(s), a wiki, etc).

At a moment a lot of these resources are not available. It's coming, and in fact a lot of these materials are already complete (or close to being completed). Regardless, whenever you have questions about Ode and cannot find answers on your own feel free to send me an email (rob at ode-is-simple.com).

1. Some knowledge of the Perl language and general programming concepts

For anyone new to porgramming, Ode is, in my opinion, a perfect place to start. In fact, Ode was written as an academic project designed to serve as a suitable first introduction to programming and intended to address what I believe to be key failings with the way we introduce new students to programming and the field of computer science.

This was the basis of my masters thesis. Consider this excerpt from the introduction:

There are two important objectives that we must achieve in order to be successful in attracting new students.

First, as I've already discussed, there's a disconnect between the work students imagine they may want to do with a CS education and what they're able to accomplish early in their academic career(s). We need to bridge this gap by providing projects that can help them recognize the relevance of what they're learning to work that is intrinsically motivational. The job of bringing new students to the field is as much a matter of encouragement and inspiration as it is education.

The limited, uninspired work that often characterizes introductory programming courses sends the wrong message to new students, suggesting that they're unprepared to face more difficult work that lies ahead of them and leaving them feeling insecure about their abilities as new programmers. An ideal solution would introduce students to foundational topics and do so in a way that builds confidence and piques their interest by affording them the opportunity to do work they find rewarding. I claim that the web is a perfect bridge between the world of CS and mainstream computer technologies.

First, we don't have to wonder if the web is engaging. It is experiencing phenomenal growth and attracting a lot of interest generally, and among those people who we might hope to attract to the field.

Secondly, not only is the web popular but it is legitimately relevant to Computer Science and represents a tremendously valuable resource for the community. Today, the web is becoming a distributed platform for building applications, with the elegance of a modern framework and the capabilities of a service-oriented architecture; one that is already here, widely used, and global in scale. Furthermore, many familiar CS problems are making their way to the web, which suggests that it may be a useful platform for vetting our ideas related to these problems. For example, the emergence of open standards has led to the accessibility of large data sets, and the opportunity to confront the real world problems associated with accessing that data over a highly distributed application.

Interested in getting an early start?

First realize that there are two different versions of each release of Ode, 'ode.cgi' and 'odeannotated.cgi'. Both executable (i.e. working scripts) and functionally identical. The difference between the two is hinted at in the file names. ode.cgi is a pretty typical perl script with minimal commenting, while 'odeannotated.cgi' contains extensive annotations.

To give you some idea of what I mean by extensive, while ode.cgi is approx 193 KB and 6,000 lines, ode_annotated.cgi is approx 1.3 MB and 36,000 lines. Those approximately 30,000 extra lines are a running description of what the code is doing and why.

There is also a third file, 'odeannotated.html', which is an html formatted version of 'odeannotated.cgi' with anchor tags corresponding to lines in the unannotated version of the script. This makes it essentially an HTML formatted index allowing you to jump between the two versions.

Let's say you find yourself digging through the script, and you have a question about a particular line, line 879 for example. You can drag and drop the HTML file to a web browser and append a pound sign and the line number to the end of the URL ('#879' in this case). The browser will jump right to the corresponding line in the annotated script, where you'll find information that might help answer your question.

The annotated source means that you're never on your own trying to decipher the code.

Now that I've said all that, do not jump right into the annotated source. That's not where you want to begin.

Pick up the book 'Learning Perl "Learning Perl page at o'reilly.com"' published by O'Reilly.

Consider this the unofficial guide to Perl for Ode. Just about everything you need to know to understand Ode at the source code level is contained in this relatively short 352 page book (there are probably closer to approximately 250+ pages of actual content). Reading just 10 pages a day, you'll be finished in about a month. I think that's pretty exciting.

When I say that 'Learning Perl' is the unofficial guide to Perl for Ode I mean that quite literally. I developed the project with that specific book in mind, being careful to limit what I did with the script to topics covered by the book. (To be completely honest, there are a couple of topics are covered in the 'Intermediate Perl' book but you can worry about that later - I'd guess that you won't even notice.)

Why? I wanted to have a single reference that could serve as a common resource, i.e. a shared knowledge base, for all members of the community. I chose an introductory book because I wanted the project to be accessible to the widest possible audience (also, we can do everything we need to do with the information in Learning Perl).

Is 'Learning Perl' the only introductory Perl book available? No, it's not. There are quite a few others available. (I've read at least a couple of of them.) Regardless, Learning Perl is the one and only guide to Perl for Ode.

The advantage of using one book is that it simplifies what would otherwise make for difficult and time consuming instruction and discussion.

What does this mean to you?

Discussion related to Learning Perl is considered on-topic for this project. Feel free to ask questions about the book, and even reference page numbers (the most recent edition, currently the 5th, is preferred). In fact, I encourage you to discuss information in the book even if it's not directly related to Ode.

Also, expect that answers to your questions might make reference to the book.

Why did I choose 'Learning Perl'?

It is widely available and mature. Also, I am very familiar with it and find it to be both accessible and reliable (factually accurate).

I highly recommend you pick up a copy if you don't already own it. Currently, the list price of the print edition is $39.99 with a ebook version available for $31.99. You do not need to pay this much. You can typically find any computer book at 30% - 40% off of the list price. So you should expect to pay something closer to $25.00 for the book new. (One option is to join O'Reilly's free membership program which offers savings of up to 40% off the price of books purchased directly from the publisher through oreilly.com.) If you'd rather not buy the book, you should be able to find a copy at your local library (or put in a request it). For what it's worth, I recommend you buy your own copy if you can.