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. 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 development set deadlines, not docs or quality assurance, so those deliverables are always squeezed for time in 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 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 opportunities 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.
If you think this all sounds nice but impractical, I encourage you to sign up for the newsletter to learn how to practice these techniques like you would a musical instrument. You need hands-on experience and time to play to get better and better.