It is not uncommon to have a cycle of news around communities being unfriendly to women or newcomers or people who aren't already there. By 'news' I mean someone posts something that is close to their heart about some unjustice and other people comment on it or write their own posts and generally, the moral of the story is: But we should be better than this!
This is normal and desired behavior as part of the overall community. This cycle is a good thing because it causes people to think about their behavior as community members and what it's like to be an outsider and how they can improve. These are all positive steps because it springs from an honest desire to be better people. That's awesome.
Lately, I've been poking in areas of technology where I don't tend to tread often. One area has been picking up a new piece of technology by looking at the documentation. This particular journey began by being a Glass Explorer, and that's a story that I've talked about on my own blog at amye.org, so I won't recap it here. But, late one night, as I was churning through documentation on what Android will actually do and all of these (frankly amazing) things that your smartphone hardware has the capability of doing (ambient air pressure, anyone?), it struck me that documentation is one of the great levelers of our time.
Everyone has to read documentation. Everyone. You know those times where you jump in and don't bother to read the manual and then wonder why it didn't work? Well, yes... this happens to everyone. The person 'just downloading to try it out' and the person who wrote vast swathes of the code both have a vested interest in documentation. Granted, there are different spectrums to their interest, but they are both valid. I think of it a little bit like the 3rd grade student who's just learning to read music and the professional pianist who can sightread instantly—but, they both need the score to know what the next notes to play are.
Given that context, your documentation in your open source community says something about what you expect your community to be. I realize that I am going to get plenty of comments about how your code is self-documenting. No, dear sirs and madams, it very much isn't. Expecting your code to be self-documenting is like marking individual trees in your forest without paying attention to where the forest lives. Is this in the arctic? The tropics? What sort of creatures am I likely to find under that rock when I pull it up? What am I looking at and where do I expect to be next?
I'm enjoying working through the Android documentation because it's a platform and it lets you know at nearly every turn. It's clearly defined and laid out, but there are still pieces of the vocabulary that are unfamiliar.
I ran across this tweet by @relsqui a while back and it has stuck with me...
Theory: Lack of documentation promotes impostor syndrome. "I must be supposed to know this already/be able to figure it out on my own ..."
Here's why I've held onto it—it might be a theory but a theory is the highest scientific law, and it's up to us to disprove it. There's plenty that you can do; just keeping a running text document as you get through a project is helpful as well.
Bottomline: If you're not going to document what you did for other people, how about doing it for your future self who will come back in six weeks and not remember where you were going for?
View the complete collection of Beginners in Open Source Week articles.
2 Comments