Mel Chua is a contagiously enthusiastic hacker, writer, and educator with over a decade of teaching and curriculum development experience and a solid track record in leadership positions at Red Hat, One Laptop Per Child, Sugar Labs, Fedora, and other Free, Libre, and Open Source Software (FLOSS) communities. A graduate student at Purdue University, Mel bridges academic research on successful communities with deep personal experience getting her hands dirty building them.
These days, Mel spends most of her time with on open source in education, teaching professors how to teach open source and otherwise working to push patches of successful open source cultural habits around learning and teaching "upstream" to classrooms in academia. In her hypothetically existent amounts of free time, she collects quirky textbooks, works on undergraduate engineering education reform, and plays piano, occasionally at the same time.
Authored Comments
The thing I like about your example is that you have a specific individual in mind - your wife - rather than a broad class of "developer," which is a vague catch-all that's difficult to test. How do you check whether documentation for your wife works? You show it to your wife. How do you check whether documentation for "a developer" works? Ummm....
Better to write for a specific developer - or to have that developer write it for you, as you've pointed out. Grab an intern, say you're going to teach them to do something cool, and they're going to write it up and have a piece of tech writing in their name they can get full credit for, and you'll help edit. Effectively, they pay for teaching in documentation, which is a great strategy to draw new people into a project; a "beginner's mind" can be a powerful tool if it comes with the articulateness to describe it.
Finally, in describing how you fill in documentation gaps you discover, you've perfectly illustrated the "leave things better than you found them" rules that keep projects - and living rooms - in sane shape.
But yeah, it's important to write for specific people (and get that writing tested - even briefly - but those specific people). It's why professional designers use personas instead of "market segments." I've written for my 13-year-old cousin, for my boyfriend, for my boss, the interns on my team, for developers I've admired but am too shy to ask questions of without offering something of value in return ("if you teach me how to do this, I'll write instructions from it so you'll never have to teach anyone again!"). The key, for me, is actually having those people check out the docs once I've written them. And if you haven't had your documentation ripped apart by a 13-year-old girl... it's a humbling experience.
My main motivation, personally, is the hope that someday I won't maintain <em>any</em> of the code I've written. I get bored easily - once I've finished a project sufficiently to scratch my own itch, I immediately check whether it scratches anyone else's itch... and if it does, I try to get them to make it scratch their itch <em>better</em>... and if that works, gradually other people end up doing more (and better - I'm actually not a good coder at all) development on it than I am.
At the point where they outpace me and I'm actually a bottleneck and hindrance to their efforts, I ask if they'd like to take over maintenance so I can get out of the way of their productivity. So far, everyone's said yes. And I get to keep using the software I originated. Win-win. But it depends - crucially - on having good developer docs. So I typically write these from the chat logs of the first new developer I (manually) walk through hacking on my projects, because (by definition) they contain exactly the questions needed to get a new person started.
Then I'm free to move on to my next awesome project.