SlideShare a Scribd company logo
COLLABORATING ON GIT AND GITHUB
Anne Gentle
FOR DOCUMENTATION
Questions at the end, but you
can always ask me anything:
documenting 20 cloud services
across 130 GitHub repositories
with 728 contributors in 4 years
@annegentle, #CIDMOnline
anne.gentle@rackspace.com
www.justwriteclick.com
GIT AND GITHUB
• 2005 born after spectacular Linux tooling failure
• Social web, leads to social coding
• Git is for command line, GitHub is the web interface
• Cross-platform tooling - Windows, Mac, Linux
• Merge files rather than a “lock and checkout” model
• Non-linear branching model
GITHUB VOCABULARY
Repository
Collection of stored
code
Organization
Collection of
repositories
Fork
Copy repository, copy
of repository
Issue
Defects, tasks, or
feature requests
Pull Request
Comparison of edits to
see if team wants to
accept changes
Commit
Point in time snapshot
of repository with
changes
Branch
Indicator of divergence
from base
• Command line tool
• Only place for all the
commands
GIT
• Web interface for git 

repositories
• http://github.com
• Comments, reviews, emojis
GITHUB
LET’S TALK ABOUT

PAIN POINTS
“Meet the deadline.”
“What can we get rid of before the
deadline? I know…”
“Let’s do Agile, but…”
“Devs rule - docs drool.”
flickr:cobalt123
WRITING IN
ISOLATION
flickr:mtischendorf
COLLABORATE
WHERE
USERS ARE
• Curate the audience
• Write with and for the audience
• Reward the audience
I NEED A WRITER
1. Sacrifice your first-born for headcount
and job description.
2. Come up with a pay scale.
3. Get a handful of resumes that don’t
meet the requirements.
4. Cry.
flickr:eclecticechoes
Ensure that contributors are
valued and rewarded!
• Sense of belonging
• Pay it forward (reciprocity)
• Effective, time-saving, user support
• Reputation, recruiting
MOTIVATIONS
flickr:seeminglee
LET’S CURATE
Authors
Processes
Tools
Mindsets
Attitudes
Jobs
flickr:roswellsgirl
TREAT DOCS
LIKE CODE
flickr:roswellsgirl
LONGTAIL
CONTRIBUTIONS
• Rise of the niche
• Finding like-minded people
interested in your content
• Dark corners of knowledge gap
are filled with docs
THE DOCS SUCK
In what way?
Which page?
How can I get it not to suck?
flickr:heidiandmatt
DOC ISSUES TRACKING
• Tasks, outright errors, and
feature requests
• I’ll triage the issue and guide
you in fixing it, issue reporter
• https://guides.github.com/
features/issues/
WRITERS NEVER
GET REVIEWS
Documentation system so separate
from code system that technical
reviews are through email
or
*gasp*
frozen-in-time PDF files
flickr:elkaypics
REVIEWERS FIX DOCS
“This is wrong, here’s how to fix it.”
• Working in the same
collaboration tools as technical
people gives better reviews
• We can merge as many as 50
patches per day; running four
automated tests per patch and
requiring two humans to check
the patch and click in order to
publish
UNFAIR
TREATMENT
Docs ghetto
flickr:mtischendorf
VALUE
PROPOSITION
Writer contributions, when
treated like code, are valued
equally with developer code
WHITE COAT
TOOLS
Closely guarded secrets of
proprietary toolchains with
expensive per-seat licenses.
or
Secret developer workflows
are mysterious to writers.
flickr:darthnick
BEAUTIFUL
DOCS
• Widely accepted tooling built
in the open so we make it
work for us and for devs
(readthedocs.org)
• Simple markup
• Flat file builds
• We can patch and log issues
against the tooling
ONLY DEV TEAMS
GET CI/CD
Deploying containers and micro
services oh my.
Docs, use some horrifyingly slow
proprietary tool, kthnxbai.
flickr: photohome_uk
CI/CD FOR ALL
• Docs can be published automatically after
reviewers merge them
• Docs can have simple tests to ensure
quality and that you “don’t break the build.”
• Scrape the code to build more helpful docs
(especially reference)
• https://opensource.com/business/15/7/
continuous-integration-and-continuous-
delivery-documentation
flickr:pedrovezini
DRAFTS FOR REVIEWS
• Static site generation
from a branch or fork
• Enables publishing both
drafts and final output
flickr:denverjeffrey
WHAT PAIRS WELL WITH GITHUB?
• Simple markup: Markdown, Middleman, RST
• GitHub Pages: http://pages.github.com
• Static site generators: https://staticsitegenerators.net/
• Well-documented style guide and contributor guide
• Open licensing: Creative Commons
• PenFlip is “GitHub for Writers”
• Borrowing development techniques
WHO USES GIT AND
GITHUB FOR WRITING?
• O’Reilly Media for book publishing
• GitHub uses GitHub to document GitHub
• OpenStack uses open source Git
• Rackspace Cloud documentation uses GitHub
WHAT ARE SOME
DIFFICULTIES?
• Scope and scale questions
• Official-ness
• Identity
• Naming
flickr:lamont_cranston
GITHUB BENEFITS
• Collaborate where users are
• Motivate more contributors; track and reward contributions
• Version control; release management; CI/CD
• Track issues for distributed assignments and improved quality
• Create a quality bar for entry
• Enable fine-grained reviews and attract more reviewers
• Automate tedious tasks
• Coach writing skills and build better writers out of subject matter experts
• Review incoming contributions; establish specialty teams for reviews
• Build reputation and street credibility with metrics
flickr:lnx
DISTRIBUTED
ASSIGNMENTS
You shall not pass…
• test style guide
• test syntax
• test build
QUALITY GATE
flickr:davebloggs007
END THE TEDIUM
ENABLE THE ROBOTS
• Build the docs and publish them to
drafts or staging area
• Docs are always available for
reviews
flickr:hddod
COACH BETTER 

WRITING
• Become the experts and
consultants while enabling
others to improve their writing
• The people with the
knowledge can become better
writers and learn more
empathy by writing for the
users
flickr: philgaldys
CREATE TEAMS
• We now divide the work by
deliverable: user guides,
install guides, configuration
guides
• We scrape the code as
often as we can to deliver
continuously
flickr:mortimer
BUILD A
REPUTATION
• Measure quality and
quantity
• Count contributions
and improvements
• Compare over time;
benchmark and reward
flickr:turbojoe
“We’re crazy, but we’re
writing a book in five days.”
- Anne Gentle
https://www.youtube.com/
watch?v=lYfHEy6E2n0
Ask me. Challenge me. Find out.
flickr:candelabrumdanse
The hope “that deficiencies in program specifications
could be made up by the skill of a technical writing
department… was misguided; the design of a
program and the design of its specification must be
undertaken in parallel by the same person, and they
must interact with each other.”
- C.A.R. Hoare, 1980
flickr:roswellsgirl
Git and GitHub for Documentation

More Related Content

What's hot

Grokking opensource with github
Grokking opensource with githubGrokking opensource with github
Grokking opensource with github
GoogleDeveloperStude4
 
GitHub Basics - Derek Bable
GitHub Basics - Derek BableGitHub Basics - Derek Bable
GitHub Basics - Derek Bable
"FENG "GEORGE"" YU
 
Git and github
Git and githubGit and github
Git and github
Sayantika Banik
 
Git and GitHub
Git and GitHubGit and GitHub
Git and GitHub
James Gray
 
Git n git hub
Git n git hubGit n git hub
Git n git hub
Jiwon Baek
 
Introduction to Git
Introduction to GitIntroduction to Git
Introduction to Git
Lukas Fittl
 
Git basics
Git basicsGit basics
Git basics
GHARSALLAH Mohamed
 
Git and github 101
Git and github 101Git and github 101
Git and github 101
Senthilkumar Gopal
 
Learning git
Learning gitLearning git
Learning git
Sid Anand
 
GitLab for CI/CD process
GitLab for CI/CD processGitLab for CI/CD process
GitLab for CI/CD process
HYS Enterprise
 
GitHub Actions in action
GitHub Actions in actionGitHub Actions in action
GitHub Actions in action
Oleksii Holub
 
Github basics
Github basicsGithub basics
Github basics
Radoslav Georgiev
 
Git Introduction Tutorial
Git Introduction TutorialGit Introduction Tutorial
Git Introduction Tutorial
Thomas Rausch
 
Git Lab Introduction
Git Lab IntroductionGit Lab Introduction
Git Lab Introduction
Krunal Doshi
 
Github
GithubGithub
Github
Nikhil Baby
 
Jenkins vs GitLab CI
Jenkins vs GitLab CIJenkins vs GitLab CI
Jenkins vs GitLab CI
CEE-SEC(R)
 
Introduction to Github Actions
Introduction to Github ActionsIntroduction to Github Actions
Introduction to Github Actions
Knoldus Inc.
 
Starting with Git & GitHub
Starting with Git & GitHubStarting with Git & GitHub
Starting with Git & GitHub
Nicolás Tourné
 
Git in 10 minutes
Git in 10 minutesGit in 10 minutes
Git in 10 minutes
Safique Ahmed Faruque
 
Git 101 - Crash Course in Version Control using Git
Git 101 - Crash Course in Version Control using GitGit 101 - Crash Course in Version Control using Git
Git 101 - Crash Course in Version Control using Git
Geoff Hoffman
 

What's hot (20)

Grokking opensource with github
Grokking opensource with githubGrokking opensource with github
Grokking opensource with github
 
GitHub Basics - Derek Bable
GitHub Basics - Derek BableGitHub Basics - Derek Bable
GitHub Basics - Derek Bable
 
Git and github
Git and githubGit and github
Git and github
 
Git and GitHub
Git and GitHubGit and GitHub
Git and GitHub
 
Git n git hub
Git n git hubGit n git hub
Git n git hub
 
Introduction to Git
Introduction to GitIntroduction to Git
Introduction to Git
 
Git basics
Git basicsGit basics
Git basics
 
Git and github 101
Git and github 101Git and github 101
Git and github 101
 
Learning git
Learning gitLearning git
Learning git
 
GitLab for CI/CD process
GitLab for CI/CD processGitLab for CI/CD process
GitLab for CI/CD process
 
GitHub Actions in action
GitHub Actions in actionGitHub Actions in action
GitHub Actions in action
 
Github basics
Github basicsGithub basics
Github basics
 
Git Introduction Tutorial
Git Introduction TutorialGit Introduction Tutorial
Git Introduction Tutorial
 
Git Lab Introduction
Git Lab IntroductionGit Lab Introduction
Git Lab Introduction
 
Github
GithubGithub
Github
 
Jenkins vs GitLab CI
Jenkins vs GitLab CIJenkins vs GitLab CI
Jenkins vs GitLab CI
 
Introduction to Github Actions
Introduction to Github ActionsIntroduction to Github Actions
Introduction to Github Actions
 
Starting with Git & GitHub
Starting with Git & GitHubStarting with Git & GitHub
Starting with Git & GitHub
 
Git in 10 minutes
Git in 10 minutesGit in 10 minutes
Git in 10 minutes
 
Git 101 - Crash Course in Version Control using Git
Git 101 - Crash Course in Version Control using GitGit 101 - Crash Course in Version Control using Git
Git 101 - Crash Course in Version Control using Git
 

Viewers also liked

Git 101: Git and GitHub for Beginners
Git 101: Git and GitHub for Beginners Git 101: Git and GitHub for Beginners
Git 101: Git and GitHub for Beginners
HubSpot
 
Bamboo - an introduction
Bamboo - an introductionBamboo - an introduction
Bamboo - an introduction
Sven Peters
 
Using Docker for Testing
Using Docker for TestingUsing Docker for Testing
Using Docker for Testing
Carlos Sanchez
 
Master Continuous Delivery with CloudBees Jenkins Platform
Master Continuous Delivery with CloudBees Jenkins PlatformMaster Continuous Delivery with CloudBees Jenkins Platform
Master Continuous Delivery with CloudBees Jenkins Platform
dcjuengst
 
Gitlab Training with GIT and SourceTree
Gitlab Training with GIT and SourceTreeGitlab Training with GIT and SourceTree
Gitlab Training with GIT and SourceTree
Teerapat Khunpech
 
Continuous Delivery with Jenkins and Wildfly (2014)
Continuous Delivery with Jenkins and Wildfly (2014)Continuous Delivery with Jenkins and Wildfly (2014)
Continuous Delivery with Jenkins and Wildfly (2014)
Tracy Kennedy
 
Rise of the Machines - Automate your Development
Rise of the Machines - Automate your DevelopmentRise of the Machines - Automate your Development
Rise of the Machines - Automate your Development
Sven Peters
 
Dockercon2015 bamboo
Dockercon2015 bambooDockercon2015 bamboo
Dockercon2015 bamboo
Steve Smith
 
Ic maven jenkins_sonar
Ic maven jenkins_sonarIc maven jenkins_sonar
Ic maven jenkins_sonar
Rocío Muñoz
 
Game of Codes: the Battle for CI
Game of Codes: the Battle for CIGame of Codes: the Battle for CI
Game of Codes: the Battle for CI
Atlassian
 
GitFlow, SourceTree and GitLab
GitFlow, SourceTree and GitLabGitFlow, SourceTree and GitLab
GitFlow, SourceTree and GitLab
Shinu Suresh
 
DockerCon EU 2015: Continuous Integration with Jenkins, Docker and Compose
DockerCon EU 2015: Continuous Integration with Jenkins, Docker and ComposeDockerCon EU 2015: Continuous Integration with Jenkins, Docker and Compose
DockerCon EU 2015: Continuous Integration with Jenkins, Docker and Compose
Docker, Inc.
 
Getting started with Jenkins
Getting started with JenkinsGetting started with Jenkins
Getting started with Jenkins
Edureka!
 
Jenkins Docker
Jenkins DockerJenkins Docker
Jenkins Docker
Alex Soto
 
DevOps and Continuous Delivery reference architectures for Docker
DevOps and Continuous Delivery reference architectures for DockerDevOps and Continuous Delivery reference architectures for Docker
DevOps and Continuous Delivery reference architectures for Docker
Sonatype
 
Seven Habits of Highly Effective Jenkins Users (2014 edition!)
Seven Habits of Highly Effective Jenkins Users (2014 edition!)Seven Habits of Highly Effective Jenkins Users (2014 edition!)
Seven Habits of Highly Effective Jenkins Users (2014 edition!)
Andrew Bayer
 
Speaking part 3
Speaking part 3Speaking part 3
Speaking part 3
Javier Martos
 

Viewers also liked (17)

Git 101: Git and GitHub for Beginners
Git 101: Git and GitHub for Beginners Git 101: Git and GitHub for Beginners
Git 101: Git and GitHub for Beginners
 
Bamboo - an introduction
Bamboo - an introductionBamboo - an introduction
Bamboo - an introduction
 
Using Docker for Testing
Using Docker for TestingUsing Docker for Testing
Using Docker for Testing
 
Master Continuous Delivery with CloudBees Jenkins Platform
Master Continuous Delivery with CloudBees Jenkins PlatformMaster Continuous Delivery with CloudBees Jenkins Platform
Master Continuous Delivery with CloudBees Jenkins Platform
 
Gitlab Training with GIT and SourceTree
Gitlab Training with GIT and SourceTreeGitlab Training with GIT and SourceTree
Gitlab Training with GIT and SourceTree
 
Continuous Delivery with Jenkins and Wildfly (2014)
Continuous Delivery with Jenkins and Wildfly (2014)Continuous Delivery with Jenkins and Wildfly (2014)
Continuous Delivery with Jenkins and Wildfly (2014)
 
Rise of the Machines - Automate your Development
Rise of the Machines - Automate your DevelopmentRise of the Machines - Automate your Development
Rise of the Machines - Automate your Development
 
Dockercon2015 bamboo
Dockercon2015 bambooDockercon2015 bamboo
Dockercon2015 bamboo
 
Ic maven jenkins_sonar
Ic maven jenkins_sonarIc maven jenkins_sonar
Ic maven jenkins_sonar
 
Game of Codes: the Battle for CI
Game of Codes: the Battle for CIGame of Codes: the Battle for CI
Game of Codes: the Battle for CI
 
GitFlow, SourceTree and GitLab
GitFlow, SourceTree and GitLabGitFlow, SourceTree and GitLab
GitFlow, SourceTree and GitLab
 
DockerCon EU 2015: Continuous Integration with Jenkins, Docker and Compose
DockerCon EU 2015: Continuous Integration with Jenkins, Docker and ComposeDockerCon EU 2015: Continuous Integration with Jenkins, Docker and Compose
DockerCon EU 2015: Continuous Integration with Jenkins, Docker and Compose
 
Getting started with Jenkins
Getting started with JenkinsGetting started with Jenkins
Getting started with Jenkins
 
Jenkins Docker
Jenkins DockerJenkins Docker
Jenkins Docker
 
DevOps and Continuous Delivery reference architectures for Docker
DevOps and Continuous Delivery reference architectures for DockerDevOps and Continuous Delivery reference architectures for Docker
DevOps and Continuous Delivery reference architectures for Docker
 
Seven Habits of Highly Effective Jenkins Users (2014 edition!)
Seven Habits of Highly Effective Jenkins Users (2014 edition!)Seven Habits of Highly Effective Jenkins Users (2014 edition!)
Seven Habits of Highly Effective Jenkins Users (2014 edition!)
 
Speaking part 3
Speaking part 3Speaking part 3
Speaking part 3
 

Similar to Git and GitHub for Documentation

Docs Like Code: Strategies and Stories
Docs Like Code: Strategies and StoriesDocs Like Code: Strategies and Stories
Docs Like Code: Strategies and Stories
Anne Gentle
 
Docs Like Code
Docs Like CodeDocs Like Code
Docs Like Code
Anne Gentle
 
Code the docs-yu liu
Code the docs-yu liuCode the docs-yu liu
Code the docs-yu liu
StreamNative
 
[artifactconf] Github for People Who Don't Code
[artifactconf] Github for People Who Don't Code[artifactconf] Github for People Who Don't Code
[artifactconf] Github for People Who Don't Code
Christopher Schmitt
 
Collaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source DocumentationCollaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source Documentation
Anne Gentle
 
O'Leary - Using GitHub for Enterprise and Open Source Documentation
O'Leary - Using GitHub for Enterprise and Open Source DocumentationO'Leary - Using GitHub for Enterprise and Open Source Documentation
O'Leary - Using GitHub for Enterprise and Open Source Documentation
LavaCon
 
Collaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source DocumentationCollaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source Documentation
Anne Gentle
 
Que nos espera a los ALM Dudes para el 2013?
Que nos espera a los ALM Dudes para el 2013?Que nos espera a los ALM Dudes para el 2013?
Que nos espera a los ALM Dudes para el 2013?
Bruno Capuano
 
PR workflow
PR workflowPR workflow
PR workflow
Weiqiang Zhuang
 
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...
Maxim Salnikov
 
Ruby in office time reboot
Ruby in office time rebootRuby in office time reboot
Ruby in office time reboot
Kentaro Goto
 
Git for folk who like GUIs
Git for folk who like GUIsGit for folk who like GUIs
Git for folk who like GUIs
Tim Osborn
 
Beyond Domino Designer
Beyond Domino DesignerBeyond Domino Designer
Beyond Domino Designer
Paul Withers
 
Managing changes to eZPublish Database
Managing changes to eZPublish DatabaseManaging changes to eZPublish Database
Managing changes to eZPublish Database
Gaetano Giunta
 
Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...
eZ Systems
 
Docs at Weaveworks: DX from open source to SaaS and beyond
Docs at Weaveworks: DX from open source to SaaS and beyondDocs at Weaveworks: DX from open source to SaaS and beyond
Docs at Weaveworks: DX from open source to SaaS and beyond
Luke Marsden
 
How to audit Drupal Sites for performance, content and best practices
How to audit Drupal Sites for performance, content and best practicesHow to audit Drupal Sites for performance, content and best practices
How to audit Drupal Sites for performance, content and best practices
Jon Peck
 
Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018
Den Delimarsky
 
Development Processes and Tooling
Development Processes and ToolingDevelopment Processes and Tooling
Development Processes and Tooling
Bora Bilgin
 
Introduction to GitHub Actions – How to easily automate and integrate with Gi...
Introduction to GitHub Actions – How to easily automate and integrate with Gi...Introduction to GitHub Actions – How to easily automate and integrate with Gi...
Introduction to GitHub Actions – How to easily automate and integrate with Gi...
All Things Open
 

Similar to Git and GitHub for Documentation (20)

Docs Like Code: Strategies and Stories
Docs Like Code: Strategies and StoriesDocs Like Code: Strategies and Stories
Docs Like Code: Strategies and Stories
 
Docs Like Code
Docs Like CodeDocs Like Code
Docs Like Code
 
Code the docs-yu liu
Code the docs-yu liuCode the docs-yu liu
Code the docs-yu liu
 
[artifactconf] Github for People Who Don't Code
[artifactconf] Github for People Who Don't Code[artifactconf] Github for People Who Don't Code
[artifactconf] Github for People Who Don't Code
 
Collaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source DocumentationCollaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source Documentation
 
O'Leary - Using GitHub for Enterprise and Open Source Documentation
O'Leary - Using GitHub for Enterprise and Open Source DocumentationO'Leary - Using GitHub for Enterprise and Open Source Documentation
O'Leary - Using GitHub for Enterprise and Open Source Documentation
 
Collaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source DocumentationCollaborating on GitHub for Open Source Documentation
Collaborating on GitHub for Open Source Documentation
 
Que nos espera a los ALM Dudes para el 2013?
Que nos espera a los ALM Dudes para el 2013?Que nos espera a los ALM Dudes para el 2013?
Que nos espera a los ALM Dudes para el 2013?
 
PR workflow
PR workflowPR workflow
PR workflow
 
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...
If your code could speak, what would it tell you? Let GitHub Copilot Chat hel...
 
Ruby in office time reboot
Ruby in office time rebootRuby in office time reboot
Ruby in office time reboot
 
Git for folk who like GUIs
Git for folk who like GUIsGit for folk who like GUIs
Git for folk who like GUIs
 
Beyond Domino Designer
Beyond Domino DesignerBeyond Domino Designer
Beyond Domino Designer
 
Managing changes to eZPublish Database
Managing changes to eZPublish DatabaseManaging changes to eZPublish Database
Managing changes to eZPublish Database
 
Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...
 
Docs at Weaveworks: DX from open source to SaaS and beyond
Docs at Weaveworks: DX from open source to SaaS and beyondDocs at Weaveworks: DX from open source to SaaS and beyond
Docs at Weaveworks: DX from open source to SaaS and beyond
 
How to audit Drupal Sites for performance, content and best practices
How to audit Drupal Sites for performance, content and best practicesHow to audit Drupal Sites for performance, content and best practices
How to audit Drupal Sites for performance, content and best practices
 
Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018
 
Development Processes and Tooling
Development Processes and ToolingDevelopment Processes and Tooling
Development Processes and Tooling
 
Introduction to GitHub Actions – How to easily automate and integrate with Gi...
Introduction to GitHub Actions – How to easily automate and integrate with Gi...Introduction to GitHub Actions – How to easily automate and integrate with Gi...
Introduction to GitHub Actions – How to easily automate and integrate with Gi...
 

More from Anne Gentle

Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and ConfigurationsInclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Anne Gentle
 
Docs as Code: Publishing Processes for API Experiences
Docs as Code: Publishing Processes for API ExperiencesDocs as Code: Publishing Processes for API Experiences
Docs as Code: Publishing Processes for API Experiences
Anne Gentle
 
Make an Instant Website with Webhooks
Make an Instant Website with WebhooksMake an Instant Website with Webhooks
Make an Instant Website with Webhooks
Anne Gentle
 
Deploying Apps on OpenStack
Deploying Apps on OpenStackDeploying Apps on OpenStack
Deploying Apps on OpenStack
Anne Gentle
 
Journey into Continuous Glucose Monitoring Technology as a Parent
Journey into Continuous Glucose Monitoring Technology as a ParentJourney into Continuous Glucose Monitoring Technology as a Parent
Journey into Continuous Glucose Monitoring Technology as a Parent
Anne Gentle
 
Writing a Technical Talk Proposal
Writing a Technical Talk ProposalWriting a Technical Talk Proposal
Writing a Technical Talk Proposal
Anne Gentle
 
Women in tech: Be that light
Women in tech: Be that lightWomen in tech: Be that light
Women in tech: Be that light
Anne Gentle
 
You'll Never Look at Developer Support the Same Way Again
You'll Never Look at Developer Support the Same Way AgainYou'll Never Look at Developer Support the Same Way Again
You'll Never Look at Developer Support the Same Way Again
Anne Gentle
 
So You Want to be an OpenStack Contributor
So You Want to be an OpenStack ContributorSo You Want to be an OpenStack Contributor
So You Want to be an OpenStack Contributor
Anne Gentle
 
OpenStack Doc Overview for Boot Camp
OpenStack Doc Overview for Boot CampOpenStack Doc Overview for Boot Camp
OpenStack Doc Overview for Boot Camp
Anne Gentle
 
Social Media, Social Networking, and Social Relevance in Tech Comm
Social Media, Social Networking, and Social Relevance in Tech CommSocial Media, Social Networking, and Social Relevance in Tech Comm
Social Media, Social Networking, and Social Relevance in Tech Comm
Anne Gentle
 
OpenStack How To - PyLadies ATX
OpenStack How To - PyLadies ATXOpenStack How To - PyLadies ATX
OpenStack How To - PyLadies ATX
Anne Gentle
 
Women of OpenStack breakfast welcome
Women of OpenStack breakfast welcomeWomen of OpenStack breakfast welcome
Women of OpenStack breakfast welcome
Anne Gentle
 
Social web for Tech Comm, STC March 2013
Social web for Tech Comm, STC March 2013Social web for Tech Comm, STC March 2013
Social web for Tech Comm, STC March 2013
Anne Gentle
 
OpenStack documentation & translation management 2012_summit
OpenStack documentation & translation management 2012_summitOpenStack documentation & translation management 2012_summit
OpenStack documentation & translation management 2012_summit
Anne Gentle
 
OpenStack Documentation in the Open
OpenStack Documentation in the OpenOpenStack Documentation in the Open
OpenStack Documentation in the Open
Anne Gentle
 
OpenStack Documentation Projects and Processes
OpenStack Documentation Projects and ProcessesOpenStack Documentation Projects and Processes
OpenStack Documentation Projects and Processes
Anne Gentle
 
TryStack: A Sandbox for OpenStack Users and Admins
TryStack: A Sandbox for OpenStack Users and AdminsTryStack: A Sandbox for OpenStack Users and Admins
TryStack: A Sandbox for OpenStack Users and Admins
Anne Gentle
 
Sprints and Stacks
Sprints and StacksSprints and Stacks
Sprints and Stacks
Anne Gentle
 
OpenStack Overview for Austin Cloud User Group
OpenStack Overview for Austin Cloud User GroupOpenStack Overview for Austin Cloud User Group
OpenStack Overview for Austin Cloud User Group
Anne Gentle
 

More from Anne Gentle (20)

Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and ConfigurationsInclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
 
Docs as Code: Publishing Processes for API Experiences
Docs as Code: Publishing Processes for API ExperiencesDocs as Code: Publishing Processes for API Experiences
Docs as Code: Publishing Processes for API Experiences
 
Make an Instant Website with Webhooks
Make an Instant Website with WebhooksMake an Instant Website with Webhooks
Make an Instant Website with Webhooks
 
Deploying Apps on OpenStack
Deploying Apps on OpenStackDeploying Apps on OpenStack
Deploying Apps on OpenStack
 
Journey into Continuous Glucose Monitoring Technology as a Parent
Journey into Continuous Glucose Monitoring Technology as a ParentJourney into Continuous Glucose Monitoring Technology as a Parent
Journey into Continuous Glucose Monitoring Technology as a Parent
 
Writing a Technical Talk Proposal
Writing a Technical Talk ProposalWriting a Technical Talk Proposal
Writing a Technical Talk Proposal
 
Women in tech: Be that light
Women in tech: Be that lightWomen in tech: Be that light
Women in tech: Be that light
 
You'll Never Look at Developer Support the Same Way Again
You'll Never Look at Developer Support the Same Way AgainYou'll Never Look at Developer Support the Same Way Again
You'll Never Look at Developer Support the Same Way Again
 
So You Want to be an OpenStack Contributor
So You Want to be an OpenStack ContributorSo You Want to be an OpenStack Contributor
So You Want to be an OpenStack Contributor
 
OpenStack Doc Overview for Boot Camp
OpenStack Doc Overview for Boot CampOpenStack Doc Overview for Boot Camp
OpenStack Doc Overview for Boot Camp
 
Social Media, Social Networking, and Social Relevance in Tech Comm
Social Media, Social Networking, and Social Relevance in Tech CommSocial Media, Social Networking, and Social Relevance in Tech Comm
Social Media, Social Networking, and Social Relevance in Tech Comm
 
OpenStack How To - PyLadies ATX
OpenStack How To - PyLadies ATXOpenStack How To - PyLadies ATX
OpenStack How To - PyLadies ATX
 
Women of OpenStack breakfast welcome
Women of OpenStack breakfast welcomeWomen of OpenStack breakfast welcome
Women of OpenStack breakfast welcome
 
Social web for Tech Comm, STC March 2013
Social web for Tech Comm, STC March 2013Social web for Tech Comm, STC March 2013
Social web for Tech Comm, STC March 2013
 
OpenStack documentation & translation management 2012_summit
OpenStack documentation & translation management 2012_summitOpenStack documentation & translation management 2012_summit
OpenStack documentation & translation management 2012_summit
 
OpenStack Documentation in the Open
OpenStack Documentation in the OpenOpenStack Documentation in the Open
OpenStack Documentation in the Open
 
OpenStack Documentation Projects and Processes
OpenStack Documentation Projects and ProcessesOpenStack Documentation Projects and Processes
OpenStack Documentation Projects and Processes
 
TryStack: A Sandbox for OpenStack Users and Admins
TryStack: A Sandbox for OpenStack Users and AdminsTryStack: A Sandbox for OpenStack Users and Admins
TryStack: A Sandbox for OpenStack Users and Admins
 
Sprints and Stacks
Sprints and StacksSprints and Stacks
Sprints and Stacks
 
OpenStack Overview for Austin Cloud User Group
OpenStack Overview for Austin Cloud User GroupOpenStack Overview for Austin Cloud User Group
OpenStack Overview for Austin Cloud User Group
 

Recently uploaded

Microsoft - Power Platform_G.Aspiotis.pdf
Microsoft - Power Platform_G.Aspiotis.pdfMicrosoft - Power Platform_G.Aspiotis.pdf
Microsoft - Power Platform_G.Aspiotis.pdf
Uni Systems S.M.S.A.
 
Presentation of the OECD Artificial Intelligence Review of Germany
Presentation of the OECD Artificial Intelligence Review of GermanyPresentation of the OECD Artificial Intelligence Review of Germany
Presentation of the OECD Artificial Intelligence Review of Germany
innovationoecd
 
Programming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup SlidesProgramming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup Slides
Zilliz
 
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?Cosa hanno in comune un mattoncino Lego e la backdoor XZ?
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?
Speck&Tech
 
UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6
DianaGray10
 
GraphRAG for Life Science to increase LLM accuracy
GraphRAG for Life Science to increase LLM accuracyGraphRAG for Life Science to increase LLM accuracy
GraphRAG for Life Science to increase LLM accuracy
Tomaz Bratanic
 
Building Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and MilvusBuilding Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and Milvus
Zilliz
 
TrustArc Webinar - 2024 Global Privacy Survey
TrustArc Webinar - 2024 Global Privacy SurveyTrustArc Webinar - 2024 Global Privacy Survey
TrustArc Webinar - 2024 Global Privacy Survey
TrustArc
 
National Security Agency - NSA mobile device best practices
National Security Agency - NSA mobile device best practicesNational Security Agency - NSA mobile device best practices
National Security Agency - NSA mobile device best practices
Quotidiano Piemontese
 
HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU
HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAUHCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU
HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU
panagenda
 
Video Streaming: Then, Now, and in the Future
Video Streaming: Then, Now, and in the FutureVideo Streaming: Then, Now, and in the Future
Video Streaming: Then, Now, and in the Future
Alpen-Adria-Universität
 
GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024
GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024
GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024
Neo4j
 
How to use Firebase Data Connect For Flutter
How to use Firebase Data Connect For FlutterHow to use Firebase Data Connect For Flutter
How to use Firebase Data Connect For Flutter
Daiki Mogmet Ito
 
Infrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI modelsInfrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI models
Zilliz
 
Best 20 SEO Techniques To Improve Website Visibility In SERP
Best 20 SEO Techniques To Improve Website Visibility In SERPBest 20 SEO Techniques To Improve Website Visibility In SERP
Best 20 SEO Techniques To Improve Website Visibility In SERP
Pixlogix Infotech
 
Removing Uninteresting Bytes in Software Fuzzing
Removing Uninteresting Bytes in Software FuzzingRemoving Uninteresting Bytes in Software Fuzzing
Removing Uninteresting Bytes in Software Fuzzing
Aftab Hussain
 
Mariano G Tinti - Decoding SpaceX
Mariano G Tinti - Decoding SpaceXMariano G Tinti - Decoding SpaceX
Mariano G Tinti - Decoding SpaceX
Mariano Tinti
 
Full-RAG: A modern architecture for hyper-personalization
Full-RAG: A modern architecture for hyper-personalizationFull-RAG: A modern architecture for hyper-personalization
Full-RAG: A modern architecture for hyper-personalization
Zilliz
 
UiPath Test Automation using UiPath Test Suite series, part 5
UiPath Test Automation using UiPath Test Suite series, part 5UiPath Test Automation using UiPath Test Suite series, part 5
UiPath Test Automation using UiPath Test Suite series, part 5
DianaGray10
 
Climate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing DaysClimate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing Days
Kari Kakkonen
 

Recently uploaded (20)

Microsoft - Power Platform_G.Aspiotis.pdf
Microsoft - Power Platform_G.Aspiotis.pdfMicrosoft - Power Platform_G.Aspiotis.pdf
Microsoft - Power Platform_G.Aspiotis.pdf
 
Presentation of the OECD Artificial Intelligence Review of Germany
Presentation of the OECD Artificial Intelligence Review of GermanyPresentation of the OECD Artificial Intelligence Review of Germany
Presentation of the OECD Artificial Intelligence Review of Germany
 
Programming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup SlidesProgramming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup Slides
 
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?Cosa hanno in comune un mattoncino Lego e la backdoor XZ?
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?
 
UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6
 
GraphRAG for Life Science to increase LLM accuracy
GraphRAG for Life Science to increase LLM accuracyGraphRAG for Life Science to increase LLM accuracy
GraphRAG for Life Science to increase LLM accuracy
 
Building Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and MilvusBuilding Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and Milvus
 
TrustArc Webinar - 2024 Global Privacy Survey
TrustArc Webinar - 2024 Global Privacy SurveyTrustArc Webinar - 2024 Global Privacy Survey
TrustArc Webinar - 2024 Global Privacy Survey
 
National Security Agency - NSA mobile device best practices
National Security Agency - NSA mobile device best practicesNational Security Agency - NSA mobile device best practices
National Security Agency - NSA mobile device best practices
 
HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU
HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAUHCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU
HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU
 
Video Streaming: Then, Now, and in the Future
Video Streaming: Then, Now, and in the FutureVideo Streaming: Then, Now, and in the Future
Video Streaming: Then, Now, and in the Future
 
GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024
GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024
GraphSummit Singapore | Neo4j Product Vision & Roadmap - Q2 2024
 
How to use Firebase Data Connect For Flutter
How to use Firebase Data Connect For FlutterHow to use Firebase Data Connect For Flutter
How to use Firebase Data Connect For Flutter
 
Infrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI modelsInfrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI models
 
Best 20 SEO Techniques To Improve Website Visibility In SERP
Best 20 SEO Techniques To Improve Website Visibility In SERPBest 20 SEO Techniques To Improve Website Visibility In SERP
Best 20 SEO Techniques To Improve Website Visibility In SERP
 
Removing Uninteresting Bytes in Software Fuzzing
Removing Uninteresting Bytes in Software FuzzingRemoving Uninteresting Bytes in Software Fuzzing
Removing Uninteresting Bytes in Software Fuzzing
 
Mariano G Tinti - Decoding SpaceX
Mariano G Tinti - Decoding SpaceXMariano G Tinti - Decoding SpaceX
Mariano G Tinti - Decoding SpaceX
 
Full-RAG: A modern architecture for hyper-personalization
Full-RAG: A modern architecture for hyper-personalizationFull-RAG: A modern architecture for hyper-personalization
Full-RAG: A modern architecture for hyper-personalization
 
UiPath Test Automation using UiPath Test Suite series, part 5
UiPath Test Automation using UiPath Test Suite series, part 5UiPath Test Automation using UiPath Test Suite series, part 5
UiPath Test Automation using UiPath Test Suite series, part 5
 
Climate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing DaysClimate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing Days
 

Git and GitHub for Documentation

  • 1. COLLABORATING ON GIT AND GITHUB Anne Gentle FOR DOCUMENTATION
  • 2. Questions at the end, but you can always ask me anything: documenting 20 cloud services across 130 GitHub repositories with 728 contributors in 4 years @annegentle, #CIDMOnline anne.gentle@rackspace.com www.justwriteclick.com
  • 3. GIT AND GITHUB • 2005 born after spectacular Linux tooling failure • Social web, leads to social coding • Git is for command line, GitHub is the web interface • Cross-platform tooling - Windows, Mac, Linux • Merge files rather than a “lock and checkout” model • Non-linear branching model
  • 4. GITHUB VOCABULARY Repository Collection of stored code Organization Collection of repositories Fork Copy repository, copy of repository Issue Defects, tasks, or feature requests Pull Request Comparison of edits to see if team wants to accept changes Commit Point in time snapshot of repository with changes Branch Indicator of divergence from base
  • 5. • Command line tool • Only place for all the commands GIT
  • 6. • Web interface for git 
 repositories • http://github.com • Comments, reviews, emojis GITHUB
  • 7. LET’S TALK ABOUT
 PAIN POINTS “Meet the deadline.” “What can we get rid of before the deadline? I know…” “Let’s do Agile, but…” “Devs rule - docs drool.” flickr:cobalt123
  • 9. COLLABORATE WHERE USERS ARE • Curate the audience • Write with and for the audience • Reward the audience
  • 10. I NEED A WRITER 1. Sacrifice your first-born for headcount and job description. 2. Come up with a pay scale. 3. Get a handful of resumes that don’t meet the requirements. 4. Cry. flickr:eclecticechoes
  • 11. Ensure that contributors are valued and rewarded! • Sense of belonging • Pay it forward (reciprocity) • Effective, time-saving, user support • Reputation, recruiting MOTIVATIONS flickr:seeminglee
  • 14. LONGTAIL CONTRIBUTIONS • Rise of the niche • Finding like-minded people interested in your content • Dark corners of knowledge gap are filled with docs
  • 15. THE DOCS SUCK In what way? Which page? How can I get it not to suck? flickr:heidiandmatt
  • 16. DOC ISSUES TRACKING • Tasks, outright errors, and feature requests • I’ll triage the issue and guide you in fixing it, issue reporter • https://guides.github.com/ features/issues/
  • 17. WRITERS NEVER GET REVIEWS Documentation system so separate from code system that technical reviews are through email or *gasp* frozen-in-time PDF files flickr:elkaypics
  • 18. REVIEWERS FIX DOCS “This is wrong, here’s how to fix it.” • Working in the same collaboration tools as technical people gives better reviews • We can merge as many as 50 patches per day; running four automated tests per patch and requiring two humans to check the patch and click in order to publish
  • 20. VALUE PROPOSITION Writer contributions, when treated like code, are valued equally with developer code
  • 21. WHITE COAT TOOLS Closely guarded secrets of proprietary toolchains with expensive per-seat licenses. or Secret developer workflows are mysterious to writers. flickr:darthnick
  • 22. BEAUTIFUL DOCS • Widely accepted tooling built in the open so we make it work for us and for devs (readthedocs.org) • Simple markup • Flat file builds • We can patch and log issues against the tooling
  • 23. ONLY DEV TEAMS GET CI/CD Deploying containers and micro services oh my. Docs, use some horrifyingly slow proprietary tool, kthnxbai. flickr: photohome_uk
  • 24. CI/CD FOR ALL • Docs can be published automatically after reviewers merge them • Docs can have simple tests to ensure quality and that you “don’t break the build.” • Scrape the code to build more helpful docs (especially reference) • https://opensource.com/business/15/7/ continuous-integration-and-continuous- delivery-documentation flickr:pedrovezini
  • 25. DRAFTS FOR REVIEWS • Static site generation from a branch or fork • Enables publishing both drafts and final output flickr:denverjeffrey
  • 26. WHAT PAIRS WELL WITH GITHUB? • Simple markup: Markdown, Middleman, RST • GitHub Pages: http://pages.github.com • Static site generators: https://staticsitegenerators.net/ • Well-documented style guide and contributor guide • Open licensing: Creative Commons • PenFlip is “GitHub for Writers” • Borrowing development techniques
  • 27. WHO USES GIT AND GITHUB FOR WRITING? • O’Reilly Media for book publishing • GitHub uses GitHub to document GitHub • OpenStack uses open source Git • Rackspace Cloud documentation uses GitHub
  • 28. WHAT ARE SOME DIFFICULTIES? • Scope and scale questions • Official-ness • Identity • Naming flickr:lamont_cranston
  • 29. GITHUB BENEFITS • Collaborate where users are • Motivate more contributors; track and reward contributions • Version control; release management; CI/CD • Track issues for distributed assignments and improved quality • Create a quality bar for entry • Enable fine-grained reviews and attract more reviewers • Automate tedious tasks • Coach writing skills and build better writers out of subject matter experts • Review incoming contributions; establish specialty teams for reviews • Build reputation and street credibility with metrics
  • 31. You shall not pass… • test style guide • test syntax • test build QUALITY GATE flickr:davebloggs007
  • 32. END THE TEDIUM ENABLE THE ROBOTS • Build the docs and publish them to drafts or staging area • Docs are always available for reviews flickr:hddod
  • 33. COACH BETTER 
 WRITING • Become the experts and consultants while enabling others to improve their writing • The people with the knowledge can become better writers and learn more empathy by writing for the users flickr: philgaldys
  • 34. CREATE TEAMS • We now divide the work by deliverable: user guides, install guides, configuration guides • We scrape the code as often as we can to deliver continuously flickr:mortimer
  • 35. BUILD A REPUTATION • Measure quality and quantity • Count contributions and improvements • Compare over time; benchmark and reward flickr:turbojoe
  • 36. “We’re crazy, but we’re writing a book in five days.” - Anne Gentle https://www.youtube.com/ watch?v=lYfHEy6E2n0
  • 37. Ask me. Challenge me. Find out. flickr:candelabrumdanse
  • 38. The hope “that deficiencies in program specifications could be made up by the skill of a technical writing department… was misguided; the design of a program and the design of its specification must be undertaken in parallel by the same person, and they must interact with each other.” - C.A.R. Hoare, 1980 flickr:roswellsgirl