Collaborating on Git and GitHub for Documentation
Presentation Abstract
This talk describes my findings and best practices while running a large documentation site for multiple projects spanning years of open source documentation experience. In this presentation, participants will learn about team writing collaboration using the website GitHub and the git source control tool. With pull requests and reviews, writing becomes a collaborative effort between developers and users, writers and readers.
Audience
The topic is an intermediate to advanced topic for people who already understand version control, code management, software development cycles, and documentation engineering. The audience for this talk includes writers, developers, and engineers who write documentation for varied audiences with their peers and readers. Audience members will learn about use cases they can apply to their situations and projects.
Introduction
With GitHub’s tools you can treat doc deliverables like code: automate builds, test the docs, review each submission, divide and distribute the writing work, track issues, and fix doc defects.
Treating docs like code may sound like a mismatch at first, but as you experience the collaborative power and review processes on GitHub, you can draw parallels between excellent writing and excellent code. The GitHub site’s collaboration tools for code also work well for writing with your intended audiences. There’s nothing like it for technical audiences, such as application program interface consumers, software development kit producers, and cloud computing resource users.
Meet the Presenter
Anne Gentle works in open source projects with the OpenStack project at Rackspace, using open source techniques for API design and documentation. She ensures the docs.openstack.org site contains relevant and accurate documentation for 20 projects written in Python across 130 git repositories. She advocates for cloud users and administrators by providing accurate technical information to increase OpenStack adoption as a cloud for the world. Prior to joining Rackspace in 2010, Anne worked as a community publishing consultant, providing strategic direction for professional writers who want to produce online content in collaborative ways. Her enthusiasm for community-based documentation methods prompted her to write a book about using social publishing techniques for technical documentation titled Conversation and Community: The Social Web for Documentation.