Contributing to Open Source Software Projects

This Saturday I participated in my first hackathon in Vienna, Austria. Along with roughly 60 other attendees we gathered for ROSSconf (Ruby Open Source Software Conference) in the fabulous Sektor5 offices to hear five speakers talk about the open source projects they are passionate about. They gave us an introduction to their project, and some areas where they needed help fixing bugs, or implementing a new feature.

We got to hear about Katrina Owen’s learning platform Exercism.io, Arne Brasseur’s Yaks, Lisa Passing’s passion for the distributed social network Diaspora, the work Piotr Szotkowski has done on Reek and the contribution Michal Papis has made to RVM.

After a lunch of Viennese bagels we all signed up to help ‘hack’ on the open source project that we were most interested in. For me that would be RVM.

Hacking on RVM

RVM, or the Ruby Version Manager, is an open source project that helps developers who work with the Ruby programming language manage the versions of Ruby that are installed on their systems. This, in turn, helps them manage gems (packages of code) that may have a dependency on a specific version of Ruby.

Over the past few years RVM has been maintained, and improved upon, by Michal Papis. It consists of over 27,000 lines of code, with a documentation website that reaches over 250,000 people every month. For many developers RVM is a tool that they rely on every day.

When I knew Michal would be attending ROSSconf I felt that I could offer him my skills as a frontend developer. Not to help improve the many thousands of lines of code that constitute the core of RVM but instead to help improve the RVM documentation website. While reviewing the website I realised that there were several areas that could be improved, specifically flattening the design of the website, improving the user experience and making the website more accessible to developers who may be disabled.

After careful inspection I realised that the website was built on Nanoc, a static site generator I am not familiar with, and relied on documentation written in a combination of Markdown and my least favourite language: HAML. Much of the HAML was malformed and the website had become bloated and slow. As an example, when running the site locally and making a stylistic change it would take upto 30 seconds for Nanoc to recompile all of the assets and render the page.

After we split up into project teams I was lucky enough to be joined in my crusade by Marc Greenstock and between us we suggested rewriting the website, from scratch, using Github’s free hosting service Github Pages and their own static site generator: Jekyll. This would allow us to move the documentation to an open source platform and off private hosting. It would be lightweight and rely on documentation written in Markdown. Moreover, as the website would be hosted on Github Pages it would be truly open source – editable by anyone.

The one issue that remained was the collection of malformed HAML files. This is where Marc came to the rescue. With plenty of experience in HAML he volunteered to convert RVM’s entire documentation to Markdown. In other words, ‘taking one for the team’.

While Marc entered file conversion purgatory I began working on giving the new Jekyll installation a basic style. As the hackathon was a five hour event we decided we would keep it simple and see if we could tackle three tasks. First, we would make it responsive so that the documentation would be readable on a mobile device. Secondly, we would refine the basic typography that comes with Jekyll and make the documentation more readable. Lastly, we would ensure that the documentation could be used by a disabled developer who might be using a screen reader (a common assistive device) to move through the elements on the page.

The first step in making it responsive was adding a basic set of Sass functions so that we could change the layout of the page at various screen widths. We installed a grid based on the Semantic Grid System and set about creating a two column layout that would fold into a single column layout on small devices.

Once this had been set up we looked to refine the typography that comes with the basic Jekyll installation. This meant porting across the font that is used on the current RVM website, ‘Open Sans’, which is freely available from Google’s font library. This gave the website a basic sans-serif feel which gave the text more room to breath.

Finally, and most importantly, we implemented some simple fixes to help a disabled user read RVM’s documentation. With a good heading structure, some visibly-hidden explanatory text, and clear link text it should be quite accessible out of the box. However as the documentation menu was located below the article container we wanted to give users the choice of skipping the article container and jumping to the documentation menu. To enable this we included a hidden skip to navigation link at the top of the page. With the addition of tabindex="-1" on the navigation’s heading the user could jump straight into choosing which page they wished to read.

(The website can temporarily be found on RVM’s github pages.)

Final thoughts

Between Marc and I we managed to get the lion’s share of RVM’s documentation ported into a new, responsive and accessible website in just under five hours. We set up the project so that others can contribute to its design in the future, and took a weight off Michal’s shoulders so that he could focus on working on the core of the RVM project.

ROSSconf was a brilliant conference. It opened my eyes to what can be achieved during a hack day, and to the importance of open source projects. It helped me realise that as a frontend developer there are many complex open source projects that are asking for advice on improving their user experience design or their accessibility, and this is an area where I can really give back to the community.

Not only am I looking forward to continuing to work on the RVM project with Marc and Michal, but also in the other projects that were showcased at the conference.

(This article can also be found on my blog alexwllms.com.)

Leave a Reply

Your email address will not be published. Required fields are marked *