This is a follow on to a post on opensource.com about using git and GitHub for technical documentation. In the OpenSource.com article, I discuss reviews and keeping up with contributions. This post talks about fixes and patches.
What about doc issues in GitHub, how do you get through all those?
In OpenStack, we document how to triage doc bugs, and that’s what you need to do in GitHub, is establish your process for incoming issues. Use Labels in GitHub to indicate the status and priority. Basically, you have to accept that it’s a doc bug, if it’s not a doc bug, ask for more information from the reporter. If you want to create labels for particular deliverables, like the API doc or end-user doc, you can further organize your doc issues. You will need to define priorities as well — what’s critical and must be fixed? What’s more “wishlist” and you’ll get to it when you can? If you use similar systems for both issues and pull requests you’ll have your work prioritized for you when you look at the GitHub backlog.
How can you encourage contributors to create a good pull request for docs?
The best answer for this is “documentation” but also great onboarding. Make sure someone’s first pull request is handled well with a personal touch. There’s a lot of coaching going on when you do reviews. Ensure that you’ve written up “What goes where” as this is often the hardest part of doc maintenance for a large body of work that already exists. This expansion problem is only getting harder in OpenStack as more projects are added. We’re having a lot of documentation sessions at the OpenStack Summit this week and we’d love to talk more about creating good doc patches.
One person I work with uses GitHub emojis every chance he gets when he reviews pull requests. I think that’s fun and sets a nice tone for reviews.
Nitpicking can be averted if you point to your style guide and conventions with a good orientation to a newcomer so that new contributors don’t get turned off by feeling nitpicked.
Have you heard of anyone who has combined GitHub with a different UI “top layer” to simplify the UI?
O’Reilly has done this with their Atlas platform. For reviews, the Gerrit UI has been extremely useful to a large collection of projects like OpenStack. There’s Penflip, which is a better frontend for writers than GitHub. The background story is great in that it offers anecdotes about GitHub being super successful for collaborative writing projects.
I think that GitHub itself is fine if your docs are treated like code. I think GitHub is great for technical writing, API documentation, and the like. Academic writers haven’t found GitHub that much of a match for their collaborative writing, see “The Limitations of GitHub for Writers” for example. It’s the actual terms that have to be adapted and adopted for GitHub to be a match for writers. For example, do you track doc bugs (issues) and write collaboratively with added content treated like software features? I say, yes!
If you just want simple markup like markdown for collaborative writing, check out Beegit. With git in the name I have to wonder if it’s git-backed, but couldn’t figure it out from a few minutes on their site. Looks promising but again, for treating docs like code, living and working with developers.