This is the third of a series of three posts on open source software. The discussion is geared towards non-programmers who – more frequently than expected – becomes involved in an open-source project.
Open-source is a complex paradigm, but sometimes it is also thrown into an academic abstract or grant proposal without much thought. Previously I presented a basic description of open-source and discussed some common misconceptions about OS software.
If you were involved in an open-source project as the clinical expert (i.e. not the programmer), you are likely the team member best positioned to bridge this gap. This post focuses on how you are uniquely positioned to contribute.
As an example, the information presented here are personal opinions from both coding and distributing an open source software for radiology residents called Capricorn.
Comment Your Source Code
Each open source file usually opens with a short version of the license and some copyright notice. Immediately after the copyright notice is a big-picture description of that particular piece of code. Then, before each function, a snippet of comment describes how to use each piece of the code contained below.
Ensuring that some level of big-picture annotation is available for the code will help the big-picture Visionary communicate with the coding Experts in her organization.
Decide on a License
The selection of an open source license should depend on the purpose and eventual goal of the project. Each license has fine prints that differentiates it from another, which usually fall in one of these categories:
- Do you allow your code be used in proprietary software?
- Do you allow require credit attribution within the source code, require others to display a message or logo on their user interface, or do you allow free adaptation of the code without any attribution?
- Do you plan on dual-licensing?
Capricorn is a free software created by my team whose members are either in training or faculty in academia and has no plan of commercialization. Therefore, the GNU General Public License was the most appropriate license based on our answers to these questions.
Develop a Short Pitch
When my team first started Capricorn, I had a lot of trouble describing it. I needed several solid minutes to describe the premise, the concept, and the construct of the project. Colleagues and advisors smiled and nodded politely, but you can often tell when you begin to lose a listener. People are interested in what I do for research, in Capricorn, or even in how my weekend was.
But they are 30-second interested, not 5-minute interested.
Therefore, even if you are making the code freely available, a classic entrepreneurial advice still applies: write an “elevator pitch.” Whether it is an open source project, a hypothesis-driven project, or a start-up, you want to be able to describe the project in 30 seconds or less.
Create a Website
Capricorn is a residency analytics software aimed for residents and residency administrators. It became clear very early in the process that for a resident or an educator who became excited about the project, we needed some way for this Visionary to communicate the idea to others in her residency program.
Your project needs a repository, one of the most popular being GitHub. When developing an open source project, the “git” software is what many programmers use to control the flow of their source codes. Git is a wonderful tool. Unfortunately, it is also highly technical.
Creating a separate website for your OS project has many benefits.
- Separate Your Audience – The fact that your project has a mix of programmers and non-coding experts means your audience is likely to have a similar composition. Having a separate website allows a much gentler introduction to the project, whereas your GitHub entry and ReadMe can focus on implementation.
- Show and Tell – Your project might be intuitive to the informatics expert but maybe not to the user or potential decision-makers in an implementing organization. For instance, Capricorn’s main users are radiology residents and administrators. Being able to showcase a hands-on demonstration and provide screenshots helps explaining how Capricorn improves radiology education.
- Garner Support – Project implementation is a big decision that goes beyond one person. Once your OS project attracts one developer or potential new user’s attention (i.e. an advocate), the task then becomes helping that person articulate the benefits to get more support. If you run a project like Capricorn in academia/nonprofit and cannot afford a support team, the website can make your advocate’s life much easier.
An open source project has many level of audiences. An enthusiastic user may be less adapted to discuss the technicalities, whereas an engineer may lose the forest for the trees. In particular, open source products may be inaccessible to the big-picture Visionaries due to the technical expertise necessary. Knowing the unique contributions you can make as the visionary/clinician/leader can increase the success rate and value of your project.