By Amanda Kelner, WIC Intern
Oregon State is home to an ever expanding computer science program. It is also home to a few computer science organizations that deal with projects beyond the scope of the university. One such organization is the Open Source Lab (OSL), which is grounded in open source technology and projects. Our WIC intern, Amanda Kelner, is an undergraduate studying music performance and English at OSU and is also the staff writer and media coordinator for the OSL. We wanted to know more about how writing and documentation played out in the open source world. Kelner sat down with Director Lance Albertson to learn more.
In an age of competition and ownership, the OSL and the larger open source community is working to expand a new frontier of accessibility and transparency in technology and information. The OSL is a hosting and development center for open source projects that often come from outside the lab and the university (from companies such as Facebook and IBM), as well as an experiential learning program for students in computer science. Students receive hands-on interaction with the coding and development process of real world projects. The projects the lab and other open source centers work on are exclusively focused on open source technology and software. Open source is the belief and implementation of free access to the internet and its technologies. Everything the OSL does is visible to the public in some way. Thus, user documentation is viewable by the public.
Documentation comes in many forms. While computer science does involve a great deal of code, it is just as important if not more so to document work. Documentation is an important part of the development process, both for interested parties and collaborators. Consider the function of lab reports. Lab reports detail the process with which an experiment is completed, including questions, methods, data, and interpretations. The lab report allows other scientists to review and possibly replicate the experiment. The same general principle applies to documentation in computer science. It describes anything from product function to code development to online information. The structure of this documentation varies depending on the purpose, but the goals are all the same: transparency.
In a recent convention known as PyCon, open source documentation was broken down into four genres: tutorials, how-to guides, discussions, and references. Each serves a different function depending on what the documenter is trying to accomplish. Tutorials are learning-oriented, how-tos are problem-oriented, discussions are understanding-oriented, and references are information-oriented. Albertson states all of these documentation styles are important to circulate information. “You use different types of documentation for different things. If you’re a developer looking up quick information, you would use some sort of reference manual, but if you want to see how a project was developed, you might look to the discussions the developers carried out online to figure out how they came to write a specific line of code.”
Git is one example of a program that not only facilities documentation, but stores this documentation and other data. Git is a decentralized version control system, which means it hosts and stores metadata, or data that informs or describes other data. Many programmers use Git during all phases of their development process and other Git users can view what they do. It is free to the public and a major documentation platform for open source users, which has been in operation for nearly a decade and is still used prevalently, even in a world of fast changing technology.
Programs like Git also keep track of who does what to any given project. Because open source means open access, this also allows for other developers to work on a project licensed by someone else. Every developer has their own account, so when they make changes to the code, Git, and programs like it, keep track of this. “All the history of who owns what is in the sourcecode,” Albertson says.
According to Albertson, this is an ideal situation. Often, documentation lags behind the real work. As projects progress, some developers may not put as much time in documentation as they do in the actual coding. To combat this, Albertson says, “At the lab, we try to have fresh eyes review our documentation. They tell us when something doesn’t make sense, or when it’s not working, and we work together to update and fix it.” This form of peer review is an important part of the development process at the lab. Not only documentation, but code is also reviewed by both students and full-time professionals.
The OSL works hard to continuously encourage and facilitate documentation among its workers. Like students in the capstone for WIC students in computer science, OSL students must relate to basic rhetoric, such as audience, genre, and language. The goals are all the same: transparency. As the open source community urges the next generation towards the next frontier of open access, the information and documentation must reflect the diligence and transparency of the ideology. Only then will the open source initiative and the OSL create a sustainable foundation.
