13

How can an open source project get volunteer contributors to document their contribution properly?

Real-world example:

We've got an open source project with a scripting interface. Gradually we are adding more and more script bindings to it. Obviously, users can only use our script bindings when they know they exist and what they do.

For that reason I did this:

  • I launched a sub-section on our wiki to document script bindings
  • I created a documentation template for script bindings on the wiki
  • I documented all the script bindings I made and a few I did not make using said template.
  • I added a comment to the source file where all script bindings need to be declared // When you add a script binding, remember to document it on https://wiki.example.org/scripting
  • When a developer pushed a change adding a script binding, I told them on our IRC channel Thank you for your commit. Remember to document your new script binding on https://wiki.example.org/scripting. Usual answer: Yeah, yeah, I'll do it whenever I have time. Usually they don't.
  • When one of the users I support complains about the lack of documentation, I forward said complaint to whoever made the binding or to the IRC channel in general.

None of that really helped. The majority of our script bindings are still undocumented. What else can I do to get people to document their work properly?

16

Don't merge, unless it meets your demands. All contributions are welcome, but only those that meet your standards are merged.

Whether that is test coverage, a style guide, or documentation, it shouldn't be merged until it's OK. You can choose to do it yourself when you're merging, or you can turn down the patch until it does.

As the maintainer, you are responsible for the quality of the project. You don't have infinite time (I assume), so turning down a patch because it doesn't meet the standards, and you don't have time to make it meet them is completely acceptable, and in many cases expected.

  • 2
    This should be the answer ... though trust me, this problem and answer is in no way specific to FLOSS development. – kdopen Jul 3 '15 at 16:29
  • I agree that until they start meeting the rule standards of your project and MAKING the time to annotate, as a result, then they don't truly wish to collaborate with you. – Angelfirenze Jul 3 '15 at 19:54
  • If rejected contributions are visible publicly, they can be marked with a reason so that anyone can decide to add what is needed to allow the contribution to be reconsidered. – trichoplax Jul 4 '15 at 16:23
5

I think you're missing out on a couple things: motivation, and a suitable quality standard.

It seems as if your developers aren't totally motivated. Many people (including myself) are interesting in writing the code, testing it and seeing if it works, not doing the paper work all the time for other people. The programs that I wrote in school normally suffered because my teacher would slam me due to the lack of comments, and he did it for the same reason. There was no clear words on to what the heck I was doing. I reasoned that the code made perfect sense - I had good variable names, and clear concise methods. It made perfect sense, but only to me. Even with templates, people won't do it, most of the time because they might not see the need. Therefore, I would make it so that we can help them see the need. This would likely be done through increased collaboration between your developers, and perhaps more interaction between the developers and the community. Make them feel appreciated, and show them that what they do is important to many people. It could inspire them.

As for the other part, the quality standard, make a level that makes sense, so that developers will make these documents. If their submissions don't satisfy you, don't approve of them, and instead politely reject and perhaps provide feedback, that doesn't give the impression that you want this. Similar to the two stars and a wish.

  • "not doing the paper work all the time for other people" and therein lies the problem. Documentation is the job of the developer .. not "other people". Unfortunately, this is a common attitude – kdopen Jul 3 '15 at 16:38
  • Rejecting will reduce the general willingness of people to contribute. You could find a system that allows for improving the changes - even by someone else. There are people who do not want to code much themselves, but to go through other people's code and understand it. The challenge is to find these. – Michael Schumacher Jul 3 '15 at 20:26
  • @MichaelSchumacher Rejecting will have to be done when there is a standard in quality being place. I agree with your sentiments, but at least replying with polite, constructive feedback should soften the repercussions. – Zizouz212 Jul 3 '15 at 21:22
1

Rejecting commits that don't include the documentation is to harsh and will alienate some contributors, as others have pointed out already. But treating them as second-class is something else. Define quality criterias for script-bindings. These include (but not only) the documentation. Bindings that fulfill these criteria get a constant set. Bindings without this can only be used if a certain option is set, can be removed completely with a compiler-flag and lead to a visible warning if used. That probably increases the interest in documenting it properly.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.