saturday, july 12, 2014
Strategies for fighting documentation inertia (my talk at Write the Docs, 2014)
I’ve had a lot of fun helping developers in my community (who build extensions for jailbroken iOS) improve our developer documentation wiki over the past year, so in May I gave a talk about it at Write The Docs in Portland. This conference was exciting; I don’t often meet other people who actually care about technical writing, and there were a couple hundred of us and many good conversations. There are 29 talk videos online!
The following is my talk, in video and text. I hope it’s helpful for other people who work with volunteers and documentation. You can jump to about 6:26 if you prefer to skip introductions and context.
Introduction
Hi everybody, sorry about that [setting up the slides went weird], I’m Britta, and this is what I’ve learned from reviving my community’s volunteer developer documentation wiki. I’ll explain how I ended up as a contributor, despite not being a developer at all, and then I’ll share my strategies for encouraging volunteers to help with it — with a little bit of social engineering and a lot of friendliness. Pretty much all documentation projects could use some more enthusiasm, and I wanted to share what I’ve learned so far, because hopefully this will help you with your projects too. And there’s an under construction gif [on the intro slide], because under construction gifs are pretty cool.
Context
So for a few years, our wiki looked like this:
It looks like a MediaWiki install — OK, whatever. But it was somewhat cryptic.
It started with an outdated tagline, and then it had a list of “ideas on what to add to this wiki”, as if the wiki didn’t have anything yet. It did have a lot of good pages, they were just buried. But at least it was honest — it also said “it is a real challenge for a beginner — where to start?”
This is what it looks like now:
Still looks like a MediaWiki install, pretty standard. But it’s so much more exciting now!
There’s a up to date statement of goals, there are lists of the best articles and the newest articles, there’s a picture with an in-joke just for fun, there’s a big “Getting Started” section, it’s alive!
So what happened here? There are a lot of volunteer editors who have helped make this happen. They are pretty awesome, so I listed some of them here.
But before I explain, it’s probably helpful if you know what this community is — where do these people come from, and why do they care about it?
I work for the tiny three-person company that makes Cydia, which is the alternative to the App Store for jailbroken iPhones and other iOS devices. This is documentation for writing software for jailbroken iOS. Apple is not going to document how to use their private APIs, so we have to do it!
What is jailbreaking though? Let’s say you have an iPhone and you want to write some software that shows up on the lockscreen instead of being a normal self-contained app. That’s crazy. You can’t do that. Apple just doesn’t give you a way to do that. But wait a minute…
This is a lockscreen running custom software. [Credit: Typo5 Lockscreen by Patrick Muff, using Cydget by saurik.] You can use a specialized security exploit available for free — you can download it from the internet and put it on your phone — which removes Apple’s restrictions on the operating system. Then you can write crazy new software that adds new features and customizations to any part of iOS, and people distribute and sell this software in our alternative to the App Store. These developers mostly write this stuff for fun, and they might make some money on their products, but they don’t work for us; they’re not our employees. They’re volunteers when they’re writing on the wiki.
Here’s another example — you can write software that customizes icons in cool ways. [Credit: Black UPS by Jackie Tran and mostly Glasklart by Max Rudberg, using WinterBoard by saurik.]
How do you get started writing these kinds of customizations? You’d probably want to learn about the tools and libraries that people have written for doing this, such as by reading some documentation. That’s usually a good start.
But for a long time we didn’t have much documentation. You had to figure out a lot of it on your own, and maybe ask some questions on IRC. When I started working for this company as a community manager, I was just working on user support forums and that kind of thing, because I’m not a developer. What do I know about developer documentation?
Occasionally I would poke developers and say “Oh, the wiki is looking a little neglected, maybe you should do something about that” — and they said “OK, I guess so. Sure.”
That didn’t work.
A new perspective
Here’s a story. Last year, just for fun, I started contributing to an open source project called OpenHatch, which teaches people how to contribute to open source projects. I’m a support person at heart, so I helped out by answering questions from developers about contributing. I answered questions about how to read a bug tracker, how to submit a patch, how to find the right documentation for the project they wanted to work on…that kind of thing.
But wait a minute, I’m helping developers with development questions. It turns out I know something about helping developers? OK, maybe I should actually join the developer IRC channels in my work community and see what I can do there too.
And that developer wiki — I actually know a lot about building wikis. I’ve been a Wikipedia contributor for twelve or thirteen years. I don’t know why I wasn’t feeling qualified to edit a wiki. OK, it was time to log in, click “edit”, and start fixing up that homepage.
This is what started my fight against inertia on my wiki. Contributing to open source projects can give you a new perspective on your work and new skills, and you can practice them in a low-pressure environment where people will often help you, because they want you to volunteer on their project. It’s also really fun. So, as an OpenHatch volunteer, if you have questions about being a new open source contributor, you can ask me! That’s my plug.
Strategies
Now I’m going to go through a big list of strategies that I’ve learned while working on this wiki. Some of these will resonate for you and some won’t, so I’m going to throw a bunch out there.
0) Have somebody who cares hang out where the developers are.
My first step was to show up and hang out with the developers. For me, this meant joining the IRC channels (developer chat rooms). If your community has an IRC channel, that’s probably where the developers are. But this could be a mailing list, Twitter, forums, meetups, the engineer lunch table, whatever it is in your community or at your company.
1) Talk to newcomers and beginners.
You might start by asking the experienced developers to write things, since they know a lot, and if that works, that’s great. But usually they’re busy, or they don’t know what to write, or sometimes they ignore you, because well, who are you anyway?
But enthusiastic beginners are solid gold. They want documentation, they’re looking for it, they’ll read it if it exists (if they can find it), and they ask questions that reveal what’s missing. They ask redundant questions that show that something is hard to find, which is also useful to know. You can ask “What was the search path that you used?” to help you fix why they weren’t finding it.
You can ask these beginners to write things down as they learn, because they look up to you as a more established person in the community, even if you’re really new too. They don’t know better! As they get more experienced, if you’re lucky, they’ll keep on contributing. You can have a nice pipeline going on.
1a) Help identify useful info to write down.
I started by noticing useful conversations in these developer chatrooms and very, very gently asking “Would this be useful to put on the wiki?”
It turned out that people had forgotten about the wiki. It was kind of outdated and stale, and it didn’t seem useful to them, so they weren’t using it. That meant they didn’t know what was documented and what wasn’t. It didn’t occur to them that they could actually fix it.
So I started reminding people that maybe this specific useful bit of information (that people keep asking about) would be useful to write down. A few of them started saying “OK, I can do that.”
1b) Ask encouraging questions to counter anti- documentation concerns.
But important in this is that I don’t tell people what to do. I ask very innocent, gentle questions. Here are examples of questions I’ve used when people have the impulse to not write documentation, which happened a lot at the beginning.
I would hear “If people can’t learn this part on their own, they probably can’t build successful projects, because this is difficult, so we really shouldn’t write it down.” OK, but that gives nothing to beginners who want to learn. So I asked “Can you write a ‘prerequisites’ list of what people should know before they start exploring on their own?” Somehow that didn’t feel like it would give everything away, and people started writing that.
When people said “Nobody pays attention to the docs, so we shouldn’t bother writing them”, I said that people would pay attention if we used the right teaching strategy. I asked these volunteers “What problems do people run into if they don’t read the docs? Let’s write down advice for these people too, so that when they show up on IRC and clearly did not read anything before they got started — very ‘exploratory’ learners — then we have a page for them, oriented toward people who tried something that didn’t work.”
Or I’d suggest to somebody to write something down, and they’d say “I don’t know enough to write this”, so I’d say “Can you add a ‘this is missing’ note to the right place in the wiki?” — and then often, magically, in the next few days somebody would fill out that spot. Having somebody point out that something is missing turns out to be valuable.
2) Think of it as a marketing problem. Make the homepage enticing to click!
As I was working on this, I realized…this is a marketing problem. Marketing is not a bad word. I’m trying to: identify the value of this documentation and communicate that value to people who need it, in order to get them to use it and contribute to it for other people. That’s the definition of marketing. The value of documentation is not obvious to everyone. Sometimes you have to figure out how to sell it!
Part of this was to make the homepage really enticing to click. Put the best articles way up front! Write a really grand tagline with a great statement of goals. I put a picture on the front page so that it had some kind of “visual identity”. Try to make it something to be proud of.
2a) More marketing: build new articles that attract more visitors.
Another part of marketing was that I helped build articles people wanted and then promoted those articles. For example, I helped with this giant table of open source projects that people can look at as example code. This made developers feel great since their projects were mentioned on the wiki, and this list felt valuable to people since it was a huge list of resources…so they kept sharing it on Twitter. Huh. This list was also really easy for people to contribute to, since all they had to do was log in and add their project, which meant lots of people signed up for wiki accounts (yesss).
This list was outside the normal scope of our documentation wiki, but that was OK. It attracted people to the wiki, and when people hear about it, some of them are going to want to start contributing.
3) Make writing more fun: show that people read it.
Many developers don’t ordinarily find it fun to work on documentation. Writing code is fun for them! They like discovering new things, and very importantly, they’re releasing them to an audience who wants them — an audience who says “Yes! Please give me more features! And here are all my support problems…” OK, maybe support isn’t that fun. But generally, releasing software is fun. You have this really good feedback loop with people who are using your work.
Contributing to the wiki felt lonely. Even if three people read your article that afternoon, you had no idea. Nobody said thanks — because they’d have to log into the wiki and click “edit”, and people don’t know how to edit, and they don’t know how to write on talk pages — so nobody was thanking anyone for working on the wiki.
So I wanted to show them that people are reading their work!
3a) Make it more fun by copyediting new stuff.
Whenever anyone added anything, I went in and copyedited it or added some formatting. This was an immediately visible way to prove to writers that somebody read their work. It added some feedback loop to the wiki process.
This also helped people feel more confident in contributing. A lot of these developers speak English as their third or fourth language, or writing just isn’t their main skill. And a lot of them are about fifteen — they don’t necessarily have a lot of technical writing experience yet. They appreciated getting some friendly feedback on their writing, and I added syntax highlighting to their code snippets, so it looked great. People like that!
3b) Make it more fun by making it look active.
Nobody likes hanging out in a ghost town. (OK, some people like hanging out in ghost towns, but they’re kind of weird. They’re cool, but they’re weird.) On a wiki, if there have been no edits for the past month, you’re going to think that nobody looks at the wiki, so why bother throwing your words into the void? I make sure that the “Recent Changes” page always has something on it, something in the past few days — even just some copyedits.
We list new articles on the homepage. It’s great if the homepage keeps changing with new stuff, so that it always feels fresh and active — something people feel they should check on. They know that if they add something, it’ll get featured on the homepage too.
c) Make it more fun by thanking people.
And we make it more fun by thanking people! If you write an article, and nobody says thank you, that is the definition of a thankless task.
Readers aren’t necessarily going to write thanks, even if they appreciate something, so this is something that I do. I write thanks to writers on their wiki talk pages, on IRC, on Twitter, everywhere. Writing thanks publicly on my work Twitter account shows that this is a priority for the community, and what’s funny is that by writing stuff on Twitter…who knew, you’re promoting the wiki again!
To write thanks effectively: do it right away, be really specific about what they did that was awesome, and say it publicly. [Credit: as discussed on the OpenHatch mailing list.] It makes people feel good, and it’s super easy. It’s the best.
4) Be there to give people permission.
Some of the people in my community felt like they needed permission to contribute to the wiki. These are often the very best people, because they’re very polite, and they’re very careful, and they don’t want to mess it up. Or they don’t feel like they’re qualified to write, a little bit of impostor syndrome.
So I’m there on IRC to be a person they can ask whether adding something would be a good idea. Of course, I’m always saying “Yes, go ahead! It’s OK if it’s not perfect, we’ll fix it!”
5) The docs system needs docs.
Here’s something that surprised me recently: the docs system needs docs! We had a jailbreaking conference last month, and I ran a little workshop for working on our wiki. Even though these volunteers are amazingly brilliant developers who can read assembly code, reverse engineer iOS, and write really complicated programs, they were asking me questions about MediaWiki editing syntax.
Because MediaWiki is a little frustrating and confusing for everyone, no matter how amazing they are. You need cheatsheet links and explanations of how to edit the wiki, even if your community is absolutely brilliant.
6) Leave rough edges for others to smooth out.
This part is a classic bit of wiki social engineering — you leave around a few obvious mistakes and easy tasks, like typos somewhere in the wiki, because that will entice new people to click “edit” and start contributing. They’re thinking “Oh that’s easy, I can fix that!” Once you get them to log in and make an account, that’s the first step — it’s good.
You can also make a list of easy “bite-sized” tasks for new editors, such as contributing to that list of open source projects. I put this in an obvious place on the homepage to help people get started.
6a) Write bad first drafts as motivation.
Another funny social engineering trick: writing bad first drafts as motivation for people to fix stuff. One of the best developers I know told me this recently: that if I want him to help with the wiki, I should write some really terrible documentation myself, even about something I don’t fully understand, and then show him what I did, because he’s going to be like “oh my god” and go fix it. That’s how to motivate him. It’s great advice.
This is, again, why beginners are solid gold. Experienced developers often have no idea what needs to be written — they need a draft, or an outline, or something else to get started with that isn’t a blank page. Beginners are perfect for writing this. Like me, as a beginner in a funny way since I’m not a developer.
Hmm…
Then I start wondering if this is going to end up with me becoming a developer too. What if I learned some Objective-C so that I could skip all of this work and just write documentation by myself? That starts to sound easier… This is one strategy I haven’t tried yet. It would be kind of hilarious. We’ll see.
Thanks! If you also have volunteers and you try to motivate them, I want to know what you do and learn about your strategies too.
Postscript
In response to this talk, I got a nice email from a person who noted that for his team’s wiki, it was helpful to install a MediaWiki extension that automatically displays credit to article contributors. I like this idea and might try to convince our dev wiki maintainer to add it.
comments (0)
comments are off. for new comments, my email address is brittag@gmail.com.
