Assignment 1 - Approaching a community

ASSIGNMENT 1 - Approaching the community

What am I working on

I have chosen to contribute to Hypothes.is throughout this course and hopefully beyond that. Hypothes.is is an online highlighting tool, which allows users to highlight, comment and share content on websites. The idea of being able to annotate, tag and interconnect content regardless of its type or form reminds me of Tim Berners-Lee's vision of the semantic web, which makes it an highly interesting project to work on. There are several highlighting tools on the internet, but none has gathered a significant number of users yet. Hypothes.is combination of open source principles, backup from the community and its passionate core-team, makes it stand out and worthwhile to work for.

What can I offer

Before I decided to join the list of contributors I had to consider what I can offer to the project. After having taken a quick look at their git-repository I can tell that their developers have several years of work-experience and it will be hard for me to join this mature project, which has its own rule-sets and workarounds. On the other hand I have worked two years on cast.li which is an web annotation tool too. I stopped development on this project by the end of last year after struggling with attracting new users. Hypothes.is is the proof that the concept holds and I can contribute to it becoming a success by applying the first hand knowledge I gained through cast.li. This said, I have several years of programming experience, so with help from the Hypothes.is team I should be able to find something useful to do.

First contact

The first time I heard about Hypothes.is was when I attended the UI class at the UC School of Information. Jake Hartnell who happens to be Hypothes.is' product manager is taking the same class. We quickly got into a discussion about the usefulness and future of annotations on the web and I showed him my previous project cast.li. He showed great interest in the technical implementation and its design, and he asked me if I wanted to help developing Hypothes.is. It was not hard to convince me.

Generally speaking my first contact was very informal, I ran by accident into Jake and it developed from there. However later on I also used more formal ways of interacting with the community, e.g. by using the mailing list, writing comments on Githubor fleshing out their internal documentation.

Communication channels

Hypothes.is uses several communication channels to stay in contact with their contributors and to keep track of the development. The first source of information is their extensive website. It offers many kinds of information, including a page explaining how to contribute. The most important source is the git-repository called h. It includes all the core files and changes made. Especially interesting for new contributors are the INSTALL files which include a step to step guide to get the server running on different operating systems. They also use a mailing list and an archive. It seems that the mailing list is not very active at the moment, but there has been some communication in the past. It has been mostly used for communication with external partners. There is also a forum. It looks like it's new since the archive only goes back two months. Here most of the threads are started by user reporting some kind of a problem or bug. They promote a IRC channel #hypothes.is on the website for people to go to when they need help. I have been there several days, and although there are about 20 people in the chat-room did no one talk. I think that people know each other in the chat and mostly use it for contacting others via PMs. For developers they link to a site where the coding style is explained together with other practicalities like licensing and how to branch correctly. The last thing which is worth mentioning is their issue tracker. They use git's standard tracker with tags for categorizing the issues.

Barriers

I faced three main barriers while approaching the community. Firstly, I wanted to contribute, but I did not know how to get involved. I have no experience in working with open source projects, and I didn't want to make a wrong move and interrupt the developers work on the project. I was for example wondering if it would have been a good idea to introduce myself through the mailing list, but since I don't know who's on the list and since it is no crucial information I did not send a mail. In fact I focussed on physical face to face interaction until I had a better understanding of how the tools are used by Hypothes.is. Secondly, it is hard to understand where help is needed. The repository itself is not much of an help consisting of several hundred files, not counting the dependencies. Also the issue tracker didn't help much, since the reported issues were hard to understand without deeper knowledge of the Hypothes.is-tool.
Thirdly, I was drowned in communication channels. There is a mailing list, an IRC chat, a wiki, Github, a issue tracker, a forum and a website. It is hard to know where to find information when you are new to most of the technologies. All the informations are scattered between the tools and it's challenging to form a consistent picture of the tool. It is also not trivial where to ask questions, since there are many possible places and I didn't want to misuse one of the channels.

Time table

Conclusion

It took a long time before I wrote the first line of code. Most of work I did was not related to code as it was mostly about more general questions. How could a group feature look and feel like? How could it be implemented in the current version of Hypothes.is? How is the concept of groups best integrated in the tool? What makes sense for the users?

Throughout this process I have been in close contact with the core team. I have met them in their office in San Francisco and have met Jake on a nearly daily basis. The functionality I worked on was very undefined when we started our work, so close coordination with the team was necessary, but the close office made it easy to interact with them.

Retrospectively, I would say that I would not have been able to join the project if I hadn't known Jake. There are many communication channels and it is hard to figure our how to use them. I remember someone sending a mail through our mailing-list saying that in OS you should just do and ask later. If there is something wrong people will tell you. This is very different from how I approached it, however after having worked with Hypothes.is I agree. Everything is peer reviewed anyway, so there is no damage done. A bugfix that does not comply to internal coding standards is still better than a mail asking how to write code. Generally people appreciate actual work done over talk. The same is true for the communication channels. Just use them as you think (and after having read the dev. FAQ) and people will tell you if you do something wrong. In the end both will profit from it. These are my experiences with Hypothes.is, but I think they are applicable to OS projects in general.