So, I've been thinking recently about milestones in open source projects. Not code based milestones, but ... milestones in terms of a project's use and community. Usually ones that happen to you rather than ones you can create.
The one that I want to talk about today though is a bittersweet moment but one that needs to be handled correctly if you want your project to thrive:
The arrival of the idiots.
You should know that moment by now. You've got your first couple of committers, you've cut a few releases, you've seen some crazy crazy (but wonderful) person deploy this code in production ... and now this guy turns up asking questions that make absolutely no fucking sense at all and your first thought is ARGH, YOU FUCKING IDIOT, WHAT ARE YOU TALKING ABOUT?!
So ... ok, maybe the guy is an idiot. But it's far more likely that they aren't making any sense because they think about the problem you're approaching differently than you do. I mean ... they managed to read enough of the docs to find the mailing list or IRC channel. So they aren't completely illiterate. And they might not be a full time programmer, so while they know how to get a consistent mental model of the things they care about but it's harder for them to do so with code. Or whatever.
The point is: you need to find a way to communicate with this person. If your project can only be used by people with the same mental model of the problem domain, you're going to massively limit your potential user and contributor base. Possibly more importantly:
For your project to be accessible to somebody with a different mental model, you need to attract and retain a documentation contributor with that mental model so they can write the docs that make sense to them.
Or, the shorter but less polite version:
An idiot is the only person who can tell you what your docs need to make them comprehensible to other idiots.
So ... keep reframing the conversation. Keep trying different ways to explain things. Eventually you'll find one that sticks. This will probably take a while. That's ok. It's annoying, but you can't avoid it, because you're trying to cross a real conceptual barrier here. Fortunately, there's a magic formula for making it worth the effort:
"This is going to take some explaining. If I keep trying until you can figure it out, will you write it up for the docs?"
To a great extent it doesn't matter if they ever do, because so long as they say "yes" the willingness to try is established. And that means they're going to pay the fuck attention to what you're saying, which is what you really need. Because what you're really doing here is iterating towards having a better way to explain things. You may not even manage to explain it to this guy. That's ok. There'll be another idiot along shortly to experiment on.
Eventually, you should get good enough at producing a coherent explanation for the thought pattern that you explain it to somebody clearly enough they go "wow, awesome, thanks" and you get that doc patch. Might take a while, but again, that's still ok. Because in the mean time you'll have stumbled across another really important fact:
"Idiot" is usually just a short form of "person I can't yet communicate effectively with".
The most exciting thing about that realisation isn't that you need to learn how to communicate with these people, though that's hugely important. The most exciting thing is this:
If you can attract and retain idiots as community members ... they can already speak fluent idiot and can help the next one.
There's a regular user on #dbix-class that's a fantastic example of this. I like the guy. He maintains a massive network monitoring system with a complex enough feature set that a lot of the queries he's running via DBIx::Class are right at the limits of what it's capable of, and more complex than the vast majority of what I see in my day to day work. He's clearly smart in some respects. But when he tries to ask me questions about perl, he invariably sounds like an idiot. I know he isn't. But that really never seems to help. Sometimes I end up having to put him on /ignore for a couple of days to avoid losing my temper, because I know the problem is the communication barrier more than anything else and therefore my anger at him is my problem, not his.
However, some days we do better. Some days I manage to find a way of framing an explanation to him that works for him, and he goes "wow", grins, and goes away and implements what he needs. And then a few weeks later I'll find myself getting angrier and angrier trying to explain the same thing to a different user, and he'll step in and say "Don't worry, Matt, I'll take this one". And five minutes later the other user will go "wow", grin, and go away and implement what they needed. And I'll stare at my screen because, honestly, I didn't understand the explanation at all. It made absolutely no sense to me. And yet it succeeded perfectly at communicating the concept.
The funny thing is, to that other user, I know I made no sense. I was, in fact, completely and utterly useless at helping them and would probably have had an overall more positive effect by pouring myself a nice cold glass of shut the fuck up right at the start of the conversation and letting somebody else try and explain things to them right at the start - it's just fortunate that somebody was around to hand me one and take things over. Which brings me to a final and important point:
"Idiot" is usually just a short form of "person I can't yet communicate with". Which means they probably think you're an idiot, too.
So love your idiots, celeberate them, fete them, make them write idiot friendly documentation, make them hang out and talk to other idiots because they will explain things better to them. And never forget:
The day you walk into a community where you don't get the mental model, you just became one of their idiots. Act towards apparent idiots in your community accordingly, lest ye be a big fat fucking hypocrite.
Oh, and Happy New Year!
-- mst, out