Write the Docs: Britta Gustafson – Strategies to fight documentation inertia

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Britta wrapped up the talks before lunch by talking about documentation inertia. The talk was about what she learned through reviving the community wiki she works on.

For a few years the wiki had an outdated tagline and a list of ideas on what to add but no mention of the existing content. Now, though, the main page has a statement of goals, lists of interesting articles, information on how to get started, and links to get help with editing. 60 great volunteers helped contribute to this renovation.

Britta works for the 3-person company that makes Cydia. The wiki in question is the documentation for using this jailbroken OS. The wiki content is all done on a volunteer-basis to further the community. How do you get started writing about these crazy jailbroken customizations, though?

That’s where documentation comes in. For a long time, though, Cydia had very little documentation. People had to just figure it out as they went along. Britta was contributing to OpenHatch, though. It’s a project for learning how to contribute to open source projects. Through this she got experience helping developers with development problems, even though she herself is not a developer.

That gave her the confidence to start working more closely with the developers in her own community at Cydia. She threw a few strategies out there to help with this.

  • Show up and be someone who cares. If you hang out where the developers are that’s the first step.
  • Talk to newcomers and beginners. Find where the pain points are and write them down.
  • Ask encouraging questions to counter anti-documentation concerns. Write down advice for those who don’t read the docs.
  • Think of documentation as a marketing problem. Make the homepage enticing to click and put the best stuff right up front.
  • Make writing more fun. Show that there are people reading it. This can even be immediately copy-editing new writing as it’s contributed.
  • Make the wiki fun by making it look active. No one wants to contribute to a silent project.
  • Understand that the docs system needs docs. Not every editing tool is understandable to the unfamiliar.
  • Leave some rough edges for others to smooth out. Easy tasks hook other contributors.