Do girls write better documentation?

Sometimes it's amazing to me what sort of stereotypes I come up against. One that's always amused me from my male colleagues and friends is "Oh, you're a girl, you'll be better at writing documentation than I will."

As it happens, I often am better at writing documentation than my male colleagues. But it's not because of some inherent sex-linked language abilities as they claim, it's because I've worked hard at learning ways to communicate information to people. And I practice those skills every chance I get! (I even do documentation for Mailman, one of the most popular mailing list managers, in my spare time.)

As a graduate student, my communication skills are one of my biggest assets: your research won't get much traction if you can't communicate your ideas to people both in the papers you write and in your conference presentations, and it's really hard to work as a teaching assistant if you have poor communication skills. Even as an undergraduate, you're still trying to communicate ideas through your assignments and exams are basically you trying to communicate to the prof that you've understood the course material!

For a long time, I tried to avoid doing documentation much, because I didn't want to get stuck in a "girl-track" and have people assume that I couldn't code just because I was good at writing about it. It's an embarrassingly common myth, probably perpetuated by people who don't want to write, that Real Coders aren't good at documentation because their brains are too busy writing Real Code.

Carla Schroder puts the kibosh on this ridiculous notion with a series of 3 articles: Tips For Documentation Writers (This Means You Too, Ace Coders), More Tips For Documentation Writers (You Too, Ace Coders), Yet More Tips For Documentation Writers (Writing For Money!). She's talking about documentation for open source software, but a lot of the tips are useful to any student who needs to communicate ideas.

She starts with explaining why good documentation is important, and why even the most hardcore of software developers should care about explaining things well, then eases into some fairly simple suggestions to help everyone write better documentation. A lot of these tips can help you if you're writing papers. Here's some she explains that I think are probably helpful to everyone:

1. Don't assume your reader already knows everything
   
2. Use normal English, or whatever language you use
   
3. Don't worry about over-explaining! This is rarely a problem
   
4. Use examples, screenshots, diagrams to help explain
   
5. Spelling, grammar, formatting and deadlines are all important.
   

What I love about her tips are that they're all things anyone can learn to do: Thinking from the point of view of your reader may not be something that comes naturally to you, but you can always find a friend in another field and ask them to read your draft and see what they need explained. Your language skills don't have to be amazing -- if you can explain it verbally to your friends or colleagues, you can write documentation. No one expects literary greatness out of a howto or your latest assignment. And so on. So don't let your male colleagues wiggle out of documentation duty or writing their part of the group project: you can just point out that it's much easier than they think.

Do I still worry about being stuck writing things because I'm the girl on the team? Sure. But if I don't want to do it, it's usually as simple as saying no. And if I do want to do it, I also don't let a little fear of stereotyping prevent me from doing something I'm good at!

Besides, if I feel like breaking stereotypes, I can always be an ace coder who also writes decent docs. I hear those are even more hard to come by than women in science and engineering. ;)