Improve your teams productivity using GitHub for DevOps–and Docs

Source – ibm.com

As Steven Weaver recently discussed in his blog about GitHub and the DevOps toolchain, GitHub offers a powerful tool for improving your team’s collaboration and workflow. It makes processes and procedures much more repeatable and automatable.

By design, GitHub also functions as a terrific tool for capturing the “tribal knowledge” that’s embodied in your DevOps team, and turning it into documentation that can bootstrap your team into even greater productivity.

Anecdotally, IBM teams using GitHub Enterprise to provide internal documentation—for engineering design, operations, and support activities—have experienced nearly 80% fewer escalation calls from first-line, 24×7 customer support staff, because GitHub has helped capture so much more information. It often lets the first-line support staff solve the customer’s problem on the spot!

GitHub facilitates compliance tracking

GitHub also offers as an excellent way of tracking required changes and updates to compliance procedures. For example, it’s a good a way to store backup information needed for compliance audits. By using a Private GitHub repository, you can shelter sensitive information easily and regulate who has access to it. By using the GitHub “Request Review” feature, you can make sure that every required compliance reviewer signs off on any new version, easily.

Documentation is code

One thing that makes GitHub so successful in turning development information into documentation is that it complements the way most software developers like to work. They are not forced to do something different when they are creating documentation than when they are writing code. When creating documentation becomes exactly the same process as creating code, everyone on the team can (and will!) update the documentation! It becomes a great way to share information, so that everyone doesn’t actually need to dig through the lines of code or comments. This capability of sharing information is especially helpful for distributed teams.

For creating documents, GitHub-flavored Markdown is a simple text tool that’s built into GitHub and GitHub Enterprise. It’s based on the industry-wide Markdown language specification. It’s easy to learn Markdown–programmers use it for their code already. Markdown displays your documents with good readability, and it’s a standard format that’s accepted by a number of other documentation tools on the market today, for example, Slate. Furthermore, the built-in GitHub “code search” capability is great for searching documentation, especially when those late-night customer support calls arrive!

Assign a document ombudsman

Finally, here’s the last piece of the picture. Someone within the organization can set forth a README document in your Git repository, with details about expected writing style and conventions. Then everyone one the team knows what’s expected. Give that person some control over the quality and consistency of the documents. It sounds very simple, but it’s amazingly helpful, especially when someone new joins the team, or as the scope of your team’s products and tasks expands.