Hierarchy of contribution in Open Source

Introduction

Community spirit

Libre, Open Source software thrives on community spirit, mutual help, and above all, on contributions from the whole community.

There are two complementary aspects: the personal one and the collective one. On the personal level are the personal liberties guaranteed by the licences the software is released under. We are free to use it as we please, hack it as we please, redistribute it as we please, etc. This obviously appeals to our selfish, ego-centric nature. But this is complemented and tempered by the collective nature of Open Source software. We all rely on the work done by other people. Open Source software can only thrive if we nurture a strong community spirit, the notions of sharing, participating, cooperating, so that the fruit of our collective work can shine.

Pay it forward

I don't like the English term Free software very much because it leads to mistaken assumptions and expectations in the heart of many of its users. The distinction between Free beer and Free speech is well known, but many end users seem to be mistaken in the notion that since they are using "free" software, they are entitled to "free" support, and make demands without ever feeling the moral obligation to contribute anything back.

The fact that we did not pay anything in the monetary sense, for the software we use, does not mean that the software is therefore free in every sense of the term. The software that we use day in, day out, is the fruit of many people's time and labour. As we know, many such developers are actually paid for their work by large corporations for whom Open Source is a part of their strategy in pursuit of profit. All is good and well. But let's not disregard the countless people who dedicated countless hours simply out of passion, for the love of the code they develop and that they share selflessly and graciously with the rest of the community.

Open Source software thrives on community contributions. We didn't pay for our Free Software, but it doesn't mean that we shouldn't pay for it, "pay" as in: "pay it back", "pay it forward", or "give or contribute something back in return".

Users and developers

There is one notion that is widely accepted and that I would like to rebel against: the one that divides the Libre Software community into two broad categories: Users and Developers with some kind of mystical, invisible, often insurmountable divide between them.

We are all both users and developers. Or so should we be. By developer, I don't mean in the restrictive sense of creating lines of code, even if most of the time, this is the end goal! Even a complete newbie unable to come up with two lines of well-formed HTML code could be considered a developer. They can help with the whole development process by feeding back the appropriate information at the appropriate levels each according to their own experience and abilities. The only absolute requirement is some Good Will and the desire to contribute something.

And, as I am going to explain in the next section, newbies are those who have the best opportunity to contribute something valuable to an Open Source project.

The value of new users

In the best of the Open Source community spirit, new users are often welcome within the community, and provided with help and support.

However, I would like to emphasize one of the greatest missed opportunities in Open Source software. It is a mistake to put newbies in the category "Users", and only put developers in the category "Contributors".

Newbie users of Open Source software have as much to contribute as confirmed software developers. Indeed, we, developers, know our software so well that we don't even notice its flaws any more: we've gone into the habit of working around the problem. A newbie, by asking questions, is contributing a lot because it is pointing out the flaws of the software, the unintuitive nature of some of its features. If those observations by newbies are properly channelled, they provide us with a great opportunity to improve the usability and intuitiveness of Open Source software. Thus, newbies should be encouraged to redirect their question to an issue tracker, where it can be decided whether the documentation can be improved or the software itself be enhanced and made more intuitive.

Pursuit of quality and usability

I am a strong software usability advocate.

Ideally, not only the software should be bug-free and perfectly perform the tasks it was designed for, but it should also be intuitive to use and offer a smooth learning curve, allowing users to pass from the "Installing the software and learning how to use it" stage to the "Actually use the software for the user's original intention" stage as quickly as possible.

As such I will denounce everything that stands in the way, like casual regressions imposed on users; and I will promote methods and concepts that may help the positive pursuit of quality and usability. The current article is one contribution towards that goal.

Obviously, developing such a software, perfect in every way, takes time and resources. In the world of Open Source, it is best achieved through cooperation, community spirit, sharing of information and resources, with each single member of this very wide community contributing whatever they can, in the most appropriate way they can.

A hierarchy

Contributions are the key. Any Open Source software as it stands today is the culmination of all past efforts and contributions by the community of user-developers.

Different ways to contribute are presented in a hierarchy, because it is a hierarchy: not all contributions are equal. Some forms of contributions are more effective and speeds the community along the road to perfection. The time spent spent in some ways could be better used by contributing the same information in slightly different ways, etc.

Contributions nearest the top, especially those above the Great Divide, are more valuable than contributions further down the ladder. Users who have absolutely no coding abilities could still contribute up to the second topmost rung in the below hierarchy, emphasising the fact that even newbies have opportunities to contribute, documenting aspects that stump them as they learn.

A proper strategy for communities would be to emphasize having contributions and information being moved as far up the hierarchy as possible:

• from discussion threads upwards to thought-out blog entries,
• from forum support threads up to bug reports,
• from threads focussed on troubleshooting buggy symptoms up to wiki articles detailing the tests to be performed and the inferences that can be made from their results,
• etc.

The goal is to concentrate scattered information into focussed wiki articles and bug reports, heightening the chances that a patch will be submitted and committed into the code repository.

Hierarchy of contribution

Code

We sometimes hear the phrase "Code is Golden". Indeed, at the end of the day, what matters the most is the code within the software that we actually use in our daily life, whether at work or for private use. Our primary motivation is how to get the best software (i.e. the best code) so that we can move on to doing the various tasks we wanted to do in the first place.

Thus, the highest form of participation in Open Source software is actual code, in the form of patches that get committed in an openly accessible code repository.

Many Libre Open Source projects are implicitly, if not explicitly, organized as meritocracies, where regular code contributors have the biggest say on the orientation of the whole project. This is probably a reflection of the primacy of code over everything else.

Of course, not all code is equal. There is good code and bad code, good design and bad design. Bad code can be buggy, badly constructed or even downright malicious. Good code is easily maintained and provides efficient and intuitive software. But the point is that even the worst of code can be patched and improved upon.

However, not everybody is a software developer nor has the necessary skills, knowledge to be a software developer, nor even the inclination or abilities to become one. It does not mean that there is no room for such a user to become an active and valued participant. All of the rungs in the ladder below provide equal opportunities for all kinds of users to contribute to Libre Open Source software. And if each participant focusses on moving things upwards in the hierarchy, each according to its own abilities, then the whole Open Source ecosystem will benefit.

Documentation & Wiki

Ideally, software should be:

• Intuitive enough that no documentation should ever necessary.
• Mature and polished enough that no issues should ever need to be reported.

While we strive towards this ideal, we have clearly not reached it yet.

What needs to be documented is not only the normal use of a software, but also issues that may arise when things do not go well.
It is important to document not only specific issues but also symptoms, even the most generic ones (crashes, freezes, Screens of Death, etc).
Users often start using search engines looking for the symptoms they just encountered. Although so far it is not generally done, it would be useful to have a series of wiki pages leading users to ask themselves the right questions, perform the relevant tests and check the appropriate logs allowing them to narrow down the range of possible causes and to collect enough information that can be then fed to a bug tracker so that developers can address the underlying issues.

What I just described is what I feel is one of the greatest missed opportunities with regard to the use of wikis. I do not need to expand on all the common uses of wikis: HOWTOs, installation and operation manuals, guides for first time users, etc.

A wiki is the text equivalent of a code repository. Contributing to a wiki is the highest level of participation that a non-developer can reach.

Trackers

There is actually a lot to say about bug trackers (or issue trackers), about what constitutes a 'good' tracker, etc.

Let's start with some semantics. Let's not talk about "bug tracker", because there is so much more to be tracked than only bugs: feature requests (or "enhancements") of course, but also documentation issues, wiki improvements, support requests, etc. Let's simply use the word: Tracker for a web site like this one which tracks all those kinds of issues. We have then Tracker software, either stand-alone, like Bugzilla, or integrated like in this site. Then we had Tickets or Tracker threads (akin to forum threads) or Tracker wiki items with one such ticket, thread, or wiki page of each single bug, feature, request to be tracked. The exact choice of word would depend on the aspect of the tracker that one wants to emphasize.

Trackers are a key component for developers to sort out bugs and other issues, and to cooperate in order to properly address each item. Trackers are usually where developers and end users meet. Unfortunately, their use is too much developer-centric. Trackers should be redesigned to allow, encourage even, newbies to contribute in a way that is useful for themselves, for the developers and for the whole community.

Unfortunately, the use of trackers for wiki enhancements to be made or for support requests is discouraged. What's worse, I have not seen a tracker software that I actually like very much. Some tracker software is downright terrible (e.g. bugzilla), while others do a better job (e.g. drupal's project_issue module). However, all lack certain dimensions that would be necessary to reflect the multi-language, global use of Libre Software, spanning countless communities and web sites. I'll have opportunities to reflect on specific aspects of the use of trackers in the future. Meanwhile, this web site strives to do things right, with a full integration between wiki and bug tracker. Many things need to be improved but the objective of this web site is clear.

As just mentioned, trackers are mostly developer-centric, but they shouldn't necessarily be so restricted. A properly designed tracker should be used to track support requests, wiki improvements, and be used by developer and end users alike, allowing each member to have filtered (default) views fitting their respective needs and contributions.

Wiki-like tracker

The reason why trackers come third on this list, behind wikis, is because an issue that is properly documented, wiki-like, with symptoms and steps to reproduce, is only one short step away from getting fixed. A good tracker software should make it easy and even encourage people to edit the issue summary, so that the steps to reproduce can be refined, apparently similar issues can be differentiated, the underlying technical implications clarified. Many users who would thus contribute to a wiki-enhanced tracker may not be developers themselves and may not have the technical know-how to actually fix the issue, but they would make it so much easier for a developer to step in, get a quick grasp of the problem without having to wade through dozens of comments, and move on to doing what they do best: hack the code and commit a fix to the issue.

Note that a wiki-enhanced tracker does not lose any of the regular features of regular trackers (with fields for status, versions, package, comments, etc.). It gains in addition to them the beneficial features of a wiki.

Forum-like tracker

A tracker thread is one step down in our hierarchy, and resemble more discussion forum threads, albeit one where the topic of discussion is generally much more tightly controlled and is less prone to veer off topic.

Fortunately, most tracker threads are usually short, with few participants and can be resolved quickly. However, we've all seen extremely long tracker threads in some popular software about a complex bug affecting many, many people. Often, the discussion within such issues are being muddled because what users are discussing are actually similar symptoms which are not all related at the code level.

Blog

A blog is personal in nature, and is the least cooperative tool. And we don't deny the need for an individual to express itself, in an environment that it controls.

In the Grand Scheme of Libre Software contribution, blogs have their uses, too. Key players can use their own blog to express their opinions or their intents on matters related to Open Source software.

My observation is that the average blog entry is of better quality than the average forum thread. Blogs have a much higher signal/noise ratio.

Another aspect to keep in mind is the temporal nature of blogs, as opposed to wikis. Wiki articles are not dated and should represent the most accurate depiction of the topic at the current time. They can be updated by any member of the community to reflect changes, as they occur. By contrast, blogs are dated (literally so: they are timestamped and the publishing date is printed). They represent a user's knowledge and opinion at a certain time. As such, blog entries are perishable where wiki articles shouldn't be.

Blog entries are best used when this dual nature (personal expression & perishable information) is a wanted feature. On the other hand, wikis would be better suited when community editing would better serve the purpose of keeping the information fresh, complete and up to date.

Project announcements, like new software release announcements, belong to this level. They don't need to be implemented as a blog (a project's official blog, as opposed to a personal blog), but they share its dual nature:
1) temporal and perishable information ("Be informed that version x.y.z of our project was released today.")
2) there is no need for the community to be able to edit the announcement, which is the "official" (as opposed to "personal" in a personal blog) voice of the project.

The Great Divide

What I call here "The Great Divide"1 is a symbolic marker between everything that has already been discussed above, and everything that will be mentioned below.

Basically, all the tools mentioned above are all that is necessary for Libre Software users of all levels to interact and to contribute. I cannot think of a single need that cannot be covered by one of the above means.

Let's keep in mind that the goals are to encourage participation and contributions and to increase the probabilities that such contributions reach the highest possible level, according to the actual needs and the user's actual technical abilities.

All contributions made using the means discussed below (forums, mailing lists...) would serve the community better if made at a higher level, using the means discussed above (tracker, wiki, code).

That is what this site is trying to demonstrate, being organized around integrated (single login) wiki, blog and tracker services.

The integrated, single log in is a key aspect, too, if one wants to encourage and facilitate participation. One of the worst possible set up would be to use different, dedicated software to cover each basic needs, e.g. Wikimedia for the wiki, Bugzilla for the tracker and PHPBB in lieu of a blog!

For these reasons and more, this web site is dedicated to improving the integration and the tools provided, and shall never implement forums, mailing lists and the like, nor promote their use.

Forums

Again, we are reminded of the adage "Code is golden, talk is not". Forums are the embodiment of the victory of Talk over Code.

A forum software is merely a tool, and there are many different ways to make use of it. Three basic uses of forums will be discussed below, in order of decreasing value of the contribution, like this whole article. Still, each of the uses would be better implemented using one of the means discussed above.

Helping

It is very common to see people selflessly dedicating a lot of their time to help fellow Libre Software users, answering questions, providing support, and guiding newbies as they learn to use their software.

This sharing of information and mutual help is the embodiment of the best of the open source community spirit.

However, it would serve the community much better if instead of saying: "Here is the solution to your problem", they would say:

I see your problem. I have edited that wiki page here [Provide link] with the proper usage. This confusing aspect is now better documented. Check it out.

or:

I understand the root of the problem. I have filed this bug report [Provide link] where I suggest how the software could be improved so that future users will not be confused as you are, or will not experience the same problem. Meanwhile, check the bug report for a temporary work around.

This way, the user's attention is redirected to the wiki or to the tracker, gently inviting them to rely more on those resources than on the forum. Also, the help thus provided benefits not only this particular user, but all users to come.

Obviously, all of this could could take place in a tracker, where support requests can more easily be redirected in view of a more permanent fix.

Another aspect to consider here is the time/impact ratio, a concept we can discuss in more details elsewhere. Basically:

1. A developer committing code would have the greatest "time invested"/"impact on the community" ratio.
2. A helper detailing a solution in a wiki page would also have a high time/impact ratio, as the wiki can reach many users, now and in the future.
3. But a helper contributing in a forum is having a low time/impact ratio because most of the time, it is helping a single user.

Asking for support

Asking for support can be a positive way to contribute to Open Source software, but only if it is approached in the right way.

Our ultimate goal is to provide bug-free, intuitive, easy to use software. Each support request should be viewed as a bug report.

A software should be intuitive enough that users should not be confused as to how to use it.
The usage of a software should be properly documented so that should any doubt arise, users can check the documentation and help themselves without needing anyone else's time.

The documentation should be organized in a way that is congruent with how we use any software: we basically ever have only two types of questions:

1. "Here is what I want to do. How do I do it?"
2. "Here is the symptom I encountered. How do I fix it?"

The fact that either question needs to be asked should ideally be considered a deficiency in the software or in its documentation. And if the answer cannot be embedded into the software itself, but must be included within its documentation, then the documentation should be organized in a way to gently guide the user from its question to the answer; from the goal to the solution, from the symptom to the fix.

The software should be user-friendly not only for the experienced user, but also for its newbie user. Either the software should be intuitive enough that a newbie could easily grok its usage, or there should be enough documentation to guide a newbie towards mastery.

However, it is a real problem when users only know how to ask, never ever bothering to wonder how they could contribute back by filing a proper bug report, or feeding back the information they got into a wiki, etc. The problem is so bad and has been observed for such a long time that a specific term has been coined to describe such users: Help Vampire. They are a drain on limited resources, especially people's time. They expect to be served, believe to be entitled to support for software they didn't pay a dime for, without ever feeling morally obligated to contribute anything back.

Any question that is asked in a forum and that is not fed back to the higher levels (wiki or tracker) should be viewed as a wasted opportunity and a waste of resources.

The least the asker could do is feed that information back up the above hierarchy.

Discussing

Discussion, sometimes going on over long-winded threads that nobody could ever be expected to read from beginning to the end, are the most wasteful and useless use of a forum.

They say:

We have discussed this problem ad nauseam, but nothing has ever changed.

I reply:

Show me the wiki page where the summary of your discussion and your conclusions can be found.
Show me the tracker ticket where you reported this issue.

Such forum discussion threads cannot be expected to be read by any other people than the direct participants, and as such, are of very limited use to the community. And if you have a strong opinion that you are afraid might be deleted from a wiki, use your personal blog for that. If your opinions are insightful enough and expressed coherently enough, people are more likely to link to your blog entry than to the forum thread where your points, which may be valid, were scattered and expressed piecemeal.

Mailing lists

In the first draft of this document, mailing lists (email groups) were put on the same level as forums. By and large, Forums and mailing lists share the same characteristics, the same types of use... and the same patterns of misuse. Thus, everything that has been said above about forums can also be said about mailing lists. We don't need to repeat any of it.

There are however marked differences which earned forums the right to be one step above mailing lists within the hierarchy exposed here.

The first difference is integrated login. Mailing lists do not require any kind of login since the messages are delivered straight into each member's private inbox. That's also why they are popular. "Why bother going to the community if the community comes to me?" Forums on the other hand require a login. Smart distributions implement a single login for their various services, like Ubuntu's SSO implementation (Single-Sign-On) between its tracker and its forums. Forums which provide a SSO solution make it that tiny bit more likely that participants will contribute to the services (wiki, tracker) behind the same SSO service. No such thing can be implemented with mailing lists.

Even better than a SSO service (like OpenID), is a fully integrated solution like in this very web site, where a single user account is all it takes, and you have automatic access to all the services you might need to contribute. Forums do not need to be as flawed as PHPBB's implementation is, but can be, when using the proper software, fully integrated into the wider array of tools and services at the disposal of the community. There cannot be any such integration with mailing lists, which are technically necessarily a completely separate entity.

All this conspires to make it so that participants in mailing list discussions, especially Help Vampires, are even less likely to contribute upwards.

For all their flaws, I can still find one, and only one appropriate use of mailing lists: a read-only, low traffic mailing list may be judiciously used for important project announcements, advisories, etc.

IRC

Some developers like to use IRC to communicate in real time. This is actually the only good use I can think of IRC: developers actively hacking code, and needing immediate help to code forward. As clearly expressed above, code is the highest form of contribution. So if IRC chats directly and immediately support the production of code, then obviously this is a good thing.

However, suggesting that user support can be provided via IRC should be anathema. What was said above about forums can also be said about IRC, except that information shared in IRC is even more volatile than the one in forums. The medium lends to even more broken discussion, with single line comments whereas in a forum, a user has more 'room' to express itself and lay out complex ideas, together with proper HTML formatting, etc.
Forums threads are regularly read the next day by regular forum participants and indexed and found in search engines. None of this can be said about IRC. Who ever reads IRC logs??

That's why it is even more important for IRC participants to push the result of their discussion back up the above hierarchy. In my sense, the only good use of IRC is between active developers, when their IRC discussion directly leads to some code being committed in some code repository (e.g. in a git repository).

Acknowledgements

Many thanks to Jan Kok, who has worked many years as an engineer for Microsoft, for his thorough review of a draft of this article. His feedback made it so much better. The typos and grammar mistakes that stand today are either those I added after his review while expanding some sections, or those that I refused to correct despite his good advice! :)

• 1. for lack of imagination for a better term