When development teams are in the same room, it is not surprising to see diagrams being used – if only being shared via sketches made on pads, or through the use of whiteboards. Interestingly, despite the fact that OSS teams are distributed geographically, diagrams also play an important role in OSS development.

There was a helpful research done by Koji Yatani et al. at University of Toronto and Oregon State University. They studied developers on the Ubuntu project and found that developers create and distribute digitalized diagrams as opposed to physical sketches. While the uses of diagrams are specific to the Ubuntu projects, there are definitely lessons that we can learn to apply in other OSS projects to ensure successful development.

Role of Diagrams

Diagrams play a role in the Ubuntu project as part of design documentation. According to a Ubuntu developer, a diagram created in the design stage should remain as part of the project documentation. This form of design documentation is more for internal use among developers, and should not be confused with documentation for users or secondary stakeholders.

Documentation for internal use: Design diagrams in the form of ASCII arts are frequently used because they are light-weight, everybody can modify it and is without the compatibility issues that other diagramming formats have. ASCII arts are often helpful for showing how the internal structure of the code works. According to a developer in the Ubuntu team, using ASCII art for these purposes “actually works”.

Communicating complex infrastructure and algorithms: In Ubuntu development, just like any other OSS projects, communication relies primarily through the Internet. For instance, contributors often have ad-hoc meetings and informal discussions over e-mail or IRC. However, it is often difficult to express their designs clearly through such channels and contributors often argue about which is the better approach, the best tool or workflow.  Sometimes, there can also be concepts like multiple servers infrastructure that require long paragraphs to explain. In such cases, developers have produced diagrams for their proposed infrastructure or produced diagrams of already built design to communicate them clearly and more efficiently.

Ensuring long-term survival of projects: Like most OSS projects, the Ubuntu project is largely volunteer-based with a high turnover of contributors. Providing architectural diagrams of the existing system is one way to make the existing project understandable to potential contributors and lowers the barriers of entry for potential contributors. This is essential for ensuring the long-term survival of OSS projects. According to a Ubuntu developer surveyed in the study, this is in fact necessary because otherwise newcomers would be completely lost.

Challenges for Using Diagrams

It was found that OSS developers realize and understand the inconveniences of digitalized diagrams. For example, different people use different tools to generate the diagrams and it is troublesome to export and import diagrams of differing formats, creating incompatibility concerns. Another cause for concern is that sharing the diagrams is not easy. In particular, most OSS project mailing lists prohibit or frown upon attaching diagrams in postings. While OSS contributors often go around this problem by uploading them on external websites and attaching the links for the images in the postings, modifying and updating the diagrams become troublesome.

Final Thoughts…

Interestingly, despite such inconveniences, diagrams are often used in the Ubuntu project in the ways described above. This indicates that diagrams play an important role in the process of open source software development despite the lack of diagramming support.

What do you guys think? Is there any way that you use diagrams and would like to see tooling that has them being made easier for you? We have been feeling this pain that developers feel when working on such development projects. We are going to try to address them in the next few days. Let us know what you would like to see.

I am writing new articles once every 2-3 months. Interested in getting notified? Sign up here.