That’s certainly possible, but I would guess that it would be possible for a projects’ contributor teams to review documentation submissions just the same way they presently review code patches submitted.

As an (obvious) example, even when a project has a requirement that all patches be submitted with accompanying tests (and even set a high minimum coverage % for those tests), just because a patch meets this standard ‘on paper’ doesn’t thus mean the patch is accepted if/when the quality of the tests (or the patch, of course!) is poor. The project team should be able to make the same quality judgements about documentation submitted too, I would think.

That said, you bring up an interesting point about the reasonableness of the requirement in the face of unclear standards — a team would have to demonstrate (probably at first with clear stated standards and then later by saying “new docs have to be as good as existing docs”) what is meant by “docs we will accept” for this to have a chance of working else I think you’re right that the result would be “minimally-compliant doc submissions” benfiting nobody.

THanks for the feedback~!

Just a quickstart, or MSDN style? Something in between? When is the documentation provided of good enough quality to be accepted? Opinions on this vary between contributors and between patch reviewers.

I’m afraid that if you require documentation, that you just get awful unusable documentation.

Intersesting comment (as always!) but I’m not sure I entirely agree with your estimation that code-usability (I am assuming you mean more code-learnability…?) is a factor that’s due quite the primacy you assign to it. Certanly there are different coding ’styles’ and ‘approaches’. Certainly there are better and worse projects from a code-learnability/approachability standpoint (which in turn does obviously play a part in contributor-friction).

But I’m not sure that its possible to conclude that there is a vast untapped collection of potential OSS contributors just itching to volunteer their spare time/effort/energy if only they could find an OSS project whose codebase they could understand adequately.

I think that in any endeavor driven by volunteerism (and certainly OSS projects without any tie to commercial ventures like 99.9999% of OSS projects aren’t any different in this regard), the ratio of volunteers to people interested in benefiting from the efforts of volunteers is always very low. While code-approachability might help mitigate that ratio somewhat, I don’t think its the primary governor of contributors by any stretch.

Rather, I tend to think that the very reason that most people go looking for an OSS project to *use* is that the project does something for them that they could not do for themselves (usually due to insufficient technical skills and/or inadequate spare time of their own) and so this leads to a situation where the very people who should be most interested in contributing something back to the OSS projects they use are either technically unable or too time-starved to do so in any significant way.

Admittedly only anecdotally, my experience is that when someone raises an issue and is met with “great idea, we’re accepting patches” from the OSS project team, invariably the responses are more along the lines of “I would have no idea how to do that, I’m just a user of project XYZ”, “I’d love to do that, maybe in 6 months when I get a break from my daily responsibilities”, and other similar replies. Rarely if ever has anyone responded with “I tried the other night, but couldn’t for the life of me figure out where in the codebase to even make this change due to the confusing way the project is designed”.

Since I’m not aware of any comprehensive study on this phenomenon (”The Barriers to Patch Submission in OSS Projects” by The Gartner Group , etc.), I will have to admit that its obviously entirely possible that this class of potential contributor does exist out there, silently TRYING to write a patch and then deciding for themselves that the code is too unapproachably complex for them to understand and never providing that feedback so OSS contributors could be aware of it, but I also admit I’m skeptical that this is truely the case.

Have you any examples (anecdotally or otherwise) of situations you could share that exemplify this scenario to the degree of primacy you seem to assign to it as a barrier to OSS contributions?

In my own experience, when I have wanted to contribute a patch to an OSS project the code for which I have only passing familiarity, the OSS project’s team (usually via forums or otherwise) has always been quite helpful about guiding my efforts as I navigate an unfamiliar (and often sizable) codebase.

-Steve B.

Yes, I agree that the personas are often blended in read life (e.g., most people don’t –thankfully! — fit neatly into one persona or the other exclusively but are in fact an amalgam of mutliple personas…not multiple personalities, but multiple personas )

You yourself, for example, almost certainly fit into that suggested 8th persona

-Steve B.

Code usability problems ensure that code users will not want to use the code as much as the project.

I find it incredibly disheartening that this issue simply isn’t a part of the open source contribution conversation. Code usability is the elephant in the room that open source contributors simply can’t bring themselves to face, just as usability in general is a problem that most programmers can’t see into.

That’s a really interesting idea (kind of a middle-ground accomodation). I suppose we could consider a sort of hierarchy of documentation that looks something like this:

1) lowest level: code itself is self-documenting, no need for docs of any kind

2) unit tests are the documentation, no written docs needed but the tests ‘explain’ how to use the code

3) the ’sample app’ you suggest here is the documentation, no written docs needed but the implementation sample app is clear enough to grok what’s going on

4) there’s actual comprehensive written docs provided

I have to say that I have never found any OSS project of significant size where #1 was true, but that I have ‘taught myself’ how to use several complex OSS projects using #2.

The one that comes to mind off the top of my head is Ayende’s Rhino.Tools ‘framework’, for which calling the written documentation ’sparse’ is an affront to the word ’sparse’ but by reading the unit tests I was able to deduce usage patterns in the code that permitted me to make effective use of the proejct in my own work.

I think your suggestion of “you have to update some kind of ‘reference app’ that demonstrates the new feature/patch” is a pretty good alternative to asking people who may not have good documentation-writing skills to write a chapter or two in the manual.

One thing I’m thinking as I write this response now is that my suggesting fails to account for the fact that writing code and writing docs don’t just differ in how much most developer WANT to perform each task, but also differ in how much most developers CAN do each task. By asking for ‘documentation in code’ we might be acknowledging this and responding to it.

Nice suggestion and thanks for the comment.

-Steve B.