Making openFrameworks Work

(The following article originally appeared in the Creative Applications Blog)

In late February 2016, a group of openFrameworks users and educators gathered in Denver Colorado to work on improving the ways people learn and use openFrameworks (OF). They worked intensely for 3.5 days, 12 hours per day, collectively committing more than 800 people-hours to creating and improving openFrameworks learning resources. This openFrameworks Education Summit aka a “doc sprint” (the largest event of its kind) was hosted by the Emergent Digital Practices Program at the University of Denver. It brought together artists & educators from the University of Denver, Carnegie Mellon University, The School of the Art Institute of Chicago, The School for Poetic Computation, Parsons School of Design, Penn State, The School for the Visual Arts, Microsoft, Carnegie Museum of Art, and internationally from Vienna Austria, and Dresden Germany. The participants worked together to improve the approachability of OF, thus helping students around the world learn how to create with this powerful digital arts and design tool.

The Whys of Documentation

As with most open-source projects, there is a core of amazing people working in close connection to make OF happen and evolve. Known as the “TAZ” in the community, Theo Watson, Arturo Castro, and Zach Lieberman spend endless hours shaping and steering the direction of OF in consultation with the broader community. During this process they and many many others leave commented clues as to how things work in their code, there to be found if you know how to look. This has meant that experienced programmers can track down most answers they might have about how things work in OF. On the other hand, it has meant that the documentation pages of OF were left fairly barren, with just 30% of the functions of OF having any description of what they do. This is not uncommon in open-source projects as it takes massive amounts of time to upkeep the software, much less the documentation. It also requires a set of standards that contributors will follow over the long term. None of this would be very surprising except for the example set by Processing: it is not uncommon for creative coders to move to OF as they move outside the boundaries of Processing, but the stark difference in the usefulness of the documentation has made that transition difficult (that and the use of a much more complex IDE). Understanding that in some ways, much OF is too complicated to be documented with the same format as Processing, the challenge for the summit was to figure out what could be successfully accomplished with 18 people over 4 days. The larger group split into three subgroups focusing on: the basic OF learning materials, the documentation of the classes and functions, and the final editing and sharing of ofBook.

Documenting the Documentation

The most obvious changes to the basic learning materials can be seen with the “learning” page on the openFrameworks website. There you will see a major re-organization of previous links as well as many new sections. The “Getting Started!” section now leads brand new users to the right resources, and in the order they will need them. The “External Resources” section links out to other tutorials, videos, and a wiki where OF users can add links as more resources are posted elsewhere on the web. The new “How-tos” section offers short instructions and code samples for common tasks. This section was the result of feedback from many OF educators who needed to be able to point students to quick and concise examples, answering some of the most frequently asked questions for OF.

The “learning” page now also hosts the newly completed ofBook table of contents, which links to a collection of carefully written topical tutorials spanning more than 375 pages. ofBook has been a massive multiyear undertaking by many influential OF artists and users, explaining everything from drawing lines, using shaders, to memory structures in C++. Taken as a whole, the “learning” page is now the most robust and accessible resource for all levels of OF users.

A significant amount of time was also spent looking deeply at the examples that ship with openFrameworks and how they function as a major learning tool. Many of the examples were refined and new standards were set on how these examples and those that are part of ofxAddons might look and feel to better communicate what is happening in them. This new standard (already implemented in the OF Core examples for the next release) includes adding a readme file for each example with images and text describing the ideas behind the example, adding more inline code comments to the examples to help explain the pieces of the code and what they are doing, and adding more overlay text in the examples explaining what you are looking at when running the program.

The last effort is still underway - that of writing useful information for every class and function in the OF Core Documentation. First, a set of processes were put into place and adjusted to clarify the guidelines and workflows for writing documentation. Part of this is the division of the documentation behind the scenes to separate the longer class explanations with images and links from the function definitions and parameter descriptions that are part of the tooltips in your IDE. This process was then applied to many of the major openFrameworks classes to begin to make sure that all methods in openFrameworks include documentation. The process is ongoing but many parts of the documentation are now carefully and more fully explained. These will roll out with the next OF release and it should help the documentation pages become much more useful.

Bringing people to the Table

In planning this event, careful thought and funding was applied towards the goal of inviting new voices and ideas deeper into the OF community. Some of the participants were in positions at institutions that could support their travel and lodging for the event while others did not have the resources to make the trip on their own. More than half needed assistance to fly to and stay in Denver, and these are many of the same people that are likely to be part of the next generation of contributors and educators of openFrameworks. This is why these events require an inverse of the typical model where the more established you are, the more financial support you receive from the hosting institution. It also points to why a different kind of funding is required, as it is hard to raise money for emerging artists and teachers. Additionally, because this was held at an educational institution, it was a foreign notion to have major researchers in the field come and not spend significant time interacting with students. It requires longer term thinking to see how the work done at the event will have benefits to students at the institution for years to come.

The participants ranged in age and backgrounds, some having extensive experience coding openFrameworks and ofxAddons, while others had barely used the tool. This created a broad range of perspectives in the room to discuss the approaches and process being instituted. This meant that many voices were heard and change could happen quickly, pointing to why such events should happen every year for open-source projects like OF.

Support and Research

The Emergent Digital Practices program hosted the OF Educational Summit just one year after hosting the Processing Development Team for the development of Processing version 3. These efforts were spearheaded by the EDP Director, Chris Coleman, in an effort to give back to the open-source community that his program and artistic work relies on. These hosted open-source events are modeled after similar events at Carnegie Mellon University’s Frank Ritchie Studio for Creative Inquiry, The Art and Technology Department at the School of the Art Institute of Chicago, the Interactive Telecommunications Program at NYU, and The School for Poetic Computation. Free creative coding packages like Processing, P5 and OF have not only opened up worlds of possibilities, but they also free up money that was previously spent on paid software packages. We would encourage every research institution in the US (and beyond) who uses these software tools in their classrooms to find ways to support their continued development. This support might include donations, making open-source software contributions a viable research path towards tenure, or hosting events like these where massive leaps forward are made.

Many thanks to the participants: Christopher Baker, Chris Coleman, Christine de Carteret, Brannon Dorsey, Sarah Groff-Palermo, Andrew Hieronymi, Anika Hirt, Sarah Howorka, Golan Levin, Zach Lieberman, Nicole Messier, Caitlin Morris, Stacey Mulcahy, David Newbury, Caroline Record, Deborah Schmidt, Charlotte Stiles and Dan Wilcox.

And for the support provided by: The Arts, Humanities and Social Sciences Division @ DU, Emergent Digital Practices @ DU, The Marsico Visiting Scholars Fund, The Frank-Ratchye STUDIO for Creative Inquiry at Carnegie Mellon University, The School of the Art Institute of Chicago, Art and Technology Studies Department, Penn State School of Visual Arts and The School for Poetic Computation.

→ openFrameworks