User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

wiki:ghc:ghc18:az712 [2018/10/10 00:56] (current)
ebuonomo created
Line 1: Line 1:
 +AZ712: Get Going with GitHub: Documentation is Code - Conference Notes 
 +===== Presenters =====
 +Leslie Lundquist - Speakers
 +Information Architect
 +IBM Cloud
 +===== Abstract =====
 +How can we create great product documentation within an agile software development process? It takes optimal teamwork between writers and coders. I've had the experience of building several technical writing teams that are completely integrated with DevOps-style development teams. GitHub helps create excellent documentation in a fast-moving technical environment. We'll show some hands-on examples.
 +====== Session Notes ======
 +This session focused on teaching how an IBM team is treating documentation like code leveraging GitHub and Markdown. ​ Modern documentation strategies require tight collaboration between the technical writers, ​ development team, and other content contributors across the company. ​ GitHub enables a social coding environment and Markdown is an easy markup language that broader teams can easily adopt. ​
 +First and foremost, get everyone involved as stakeholders to drive support and alignment on strategy. ​ Strive to create one source of truth together and insist on social coding etiquette. ​
 +Some tactical tips for implementing this practice in your own organization:​
 +Create a common style guide for all content contributors to adhere to to drive consistency
 +Setup GitHub organization for collaboration. Create a repo.
 +Upload files and leverage GitHub flavored Markdown to author
 +Commit changes. Content/Doc team should review pull requests before merging ​
 +Jekyll builds the Markdown files and transforms into HTML
 +GitHub provides one site free. You can leverage UX designer on your team to design site and host/​deliver docs through that experience. ​
 +The benefit of this approach is the ability to cross boundaries, build broad teams, and create one source of truth for product content. The whole team’s tribal knowledge is captured for all to share. ​ Ultimately providing a better end user experience. ​
 +You can check out Leslie’s site at: 
wiki/ghc/ghc18/az712.txt · Last modified: 2018/10/10 00:56 by ebuonomo