Ask HN: Does code documentation increase contributions?

I'm trying to convince a team working on a complex open-source project that they need to document all the code they write.

They have documentation for some public APIs, but most of the code only has an occasional comment. Otherwise, there is no data structure, function, or module documentation. I.e. no explanations what they represent, or do, no member or argument descriptions, and no overall module introductions.

For now I'm trying to focus on a single argument: better code documentation will bring more outside contributors by making it easier for them to figure the code out. The project is corporate-funded, already has a lot of users, and is present in all major Linux distributions and FreeBSD, but sees little outside contributions.

To me the answer seems obvious, but I would like to hear your opinions, if possible see actual data, or at least anecdotal evidence of any effect.

General opinions on the need for most, if not all code being documented are also welcome.

Thank you!

To me, the composition of a community is probably not a technical issue and is more likely to be a social issue. In a way, this question sort of highlights the social versus technical gap.

The identified problem is lack of new outside contributors. The proposed solution:

  1. mandates more work by existing contributors.
  2. does not directly recruit outside contributors.
  3. is structured to require a cultural shift of
     the existing community.
  4. is a hypothetical without support from reasonable
     evidence.

To put it another way, what I see from across the internet is a community that makes changes by argument rather than consensus, and reaches out to the world of potential contributors for support to win the argument. It doesn't seem to be so much about writing good documentation or determining what documentation is actually necessary for the purpose. It's more rallying the troops.

Curious about what the project is and why someone might want to contribute.

Good luck.

Thank you for a thoughtful response. I'm a bit confused by your answer, though, because my problem was the lack of documentation, and making it easier for external contributors was an argument I was using, not the other way around. However, I think I see your points, and I would agree with them otherwise.

I experienced the problem first-hand, trying to add a feature to a complicated piece of code almost devoid of documentation, and spending a lot of time and energy on trying to hold everything in my head. Eventually I gave up and changed my approach, succeeding in the end, but documentation would have made it much easier, in my opinion.

I approached the team suggesting a few measures we could implement, with increasing levels of effort, and argued that they will help us get more external contributions, since that was an already recognized problem and easier to argue for. It seemed logical to me, coming from my experience. I.e. making it easier to understand the code would make it easier to contribute. There are other arguments I could have used, but they are harder to defend, and some of them especially so, since the team already knows the code well.

There were a variety of responses, but also one request for actual data on the effect of code documentation on number of contributors, which I came asking for here, after my Google searches failed. I.e. I'm asking for evidence, supporting or otherwise.

I agree that community composition is mostly a social issue. I'm intrigued by your description: "a community that makes changes by argument rather than consensus". Could you elaborate? I feel I could learn something here.

I would rather not specify the project to keep the discussion abstract and unbiased. Although for anyone really interested that information is a few Google searches away, I expect.

People might want to contribute fixes or small features, because the project is already quite widely used and is essential for bigger companies using Linux.

Thank you. I have to admit, that it's again hard for me to pinpoint what exactly you're answering to and what's your argument. Either because I'm not that smart, I'm unwilling to accept some of what you say (for whatever psychological reason/bias), it is somewhat obscure, or all together. So, please forgive me, if I fail.

First of all, I'm not sure this is exactly an XY problem, because I started the discussion describing what exactly I was doing, what difficulties I faced, and how documentation can help solve them, in my opinion (yes, opinion). So there was no confusion what I want to actually achieve. I.e. faster and easier understanding of the code, which is the primary function of documentation. I.e. you read documentation, instead of reading code (sometimes many functions deep), thus saving time and effort. At least with sufficiently good documentation.

A counter argument was that documentation is not necessary, and the code alone is enough. Another was that tests are better than documentation, because they're verified to be correct. One person replied that when they started, they also tried to write documentation, but were discouraged by the project leader, and now they also support that approach. All of that is beside the point of the discussion, although provides context.

Yes, there is no evidence supporting the particular argument I was using. I was attempting to use logic and induction to change other people's opinion, so that they don't see documentation as a thing that "doesn't matter very much". It is hard to evaluate the effect of documentation and provide evidence without extensive data and research, similarly to how it is hard to evaluate why exactly the developer time was spent. I would be glad to see evidence, though.

OK, now I'll try to calm down a little, lower my defenses, and dig at the root of the problem.

The code is a mess, there is a metric shitload of it, and it is hard to understand. I wanted no more of that pain, and I wanted to have that fixed. I.e. to have the code easier to understand, no matter how. Perhaps this is exactly what I should have written. Instead I simply wrote that the code was complex (which is true enough) to try not to trigger other people's defenses, thinking that perhaps arguing for the documentation would be easier. I know that documentation helps, in many ways, but it would be just one way of fixing it. That way was also against the popular opinion, as it turned out. I may have also had a bias against people doing "the wrong thing" (TM), since I always document my own code.

So, perhaps, this situation and my approach is what you mean by the XY problem. I don't think that my proposed means are completely at odds with the ends, but I agree that they're unnecessarily limiting, rigid. I think that I would have been better off simply raising the issue itself and asking for solutions. Especially, since that particular piece of code is already considered problematic by many. Perhaps that's what I'll do.

I had issues with some people from that community before, and I do have my own communication difficulties, which makes it more complicated, and perhaps contributed to my choice of approach. Perhaps I'm a considerable part of that particular community problems too.

Please excuse me, if the above attempt at self-reflection is too personal for a stranger's HN comment. Thank you.