
Ask HN: Does code documentation increase contributions? - spbnick
I&#x27;m trying to convince a team working on a complex open-source project that they need to document all the code they write.<p>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.<p>For now I&#x27;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.<p>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.<p>General opinions on the need for most, if not all code being documented are also welcome.<p>Thank you!
======
brudgers
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
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
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
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.

------
jjgreen
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
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.

