Collaborating on GitHub for Documentation

Home/Publications/CIDM eNews/CIDM eNews 03.18/Collaborating on GitHub for Documentation

Anne Gentle, Docs|Code (used with permission)

Let’s admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you’re flat-out wrong or a terrible typist. This happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when deadlines are set by development, not docs or quality assurance, so those deliverables are always squeezed for time at the end. Less context, less empathy, less collaboration. What to do?

All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips with each other through the documentation.

As Andy Oram said so well in “Educating computer users: the need for community/author collaboration,” “…the value in educational content lies in context (what immediate problem the reader is trying to solve) and timeliness (what’s true today will be outdated tomorrow).”

Value, context, and timeliness, all these features are available when you use GitHub to co-author your documentation.

Motivations

When you write with people beyond your immediate team, ensure that those contributors are valued and rewarded! Keep in mind these motivations people have for making information better:

  • Feel a sense of belonging.
  • Meet a desire to pay it forward (reciprocity).
  • Produce effective, time-saving, user support.
  • Build a reputation, recruiting.

Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It’s about creating opportunity to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close