4 ms·

Ask HN: Does code documentation increase contributions?

3 points by spbnick 10y ago

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!

jjgreen 10y ago
Documentation has a cost, and a risk. It must be maintained when the code changes, if not one deceives future developers and increase the chance of bugs. Ideally the code itself should be documentation enough; keep code comments for complex parts of the code which are not obvious -- these comments then stand-out because they are rare. The only place where you should document the obvious is in the public API, so I'd say the existing team are probably on the right path. Sorry :-)
- spbnick 10y ago
  Thanks! Yes, I hear the same from them and I try to consider this approach :) It is an additional effort, for sure. It is not without its benefits, though, and I'm trying to find out if it's worth it. Why I originally brought this up with them is because I started working on a feature and found the code barely comprehensible. I spent a lot of time to try to keep everything in my head and failing repeatedly and felt like documentation would have helped me a lot. I.e. I was exactly in the position of a new external contributor and found the experience lacking.
brudgers 10y ago
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.
- spbnick 10y ago
  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.

brudgers 10y ago
The question is asking for evidence to support an opinion. That opinion is held despite a lack of evidence. That's fine, in so far as it goes. In this case however, the opinion comes with a mandate that makes work for other people even though there is no evidence that the additional work will be of net benefit. For example, the community could devote 100 developer-hours per year to documentation that saves a total of 2 developer-hours per year. In this case, a proposal was made, someone asked for evidence and the person making the proposal realized their was none. The culture of the community is such that the response was an effort by the proposer to win the argument that runs against the general consensus of the community. Even though the proposer acknowledges a lack of evidence to support the proposal and can reason that their own proposal was made on the basis of something other than evidence. That's sort of what politics or community infighting etc. look like. The advantage arguing over opinions offers is that actually reaching out and engaging potential community members is harder than saying "We need more documentation". That's a common manifestation of XY Problems in social/community settings. To step to a higher level, the language -- "argue", "defend", and "would have saved me time" -- occasionally work in unusual circumstances. But a lot of people don't enjoy arguing over things that don't really matter very much. Such people will simply walk away no matter how good the documentation is. To put it another way, an unwillingness to name the project shows exactly how this is an XY Problem. The means are at odds with the ends. The fight club is probably not a good model for a software project. Good luck.
- spbnick 10y ago
  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.