GitHub Workflows for Technical Communication

GitHub Workflows for
Technical Communicators
Nicky Bleiel
Watson Information Developer, IBM
STC Conduit Conference
April 1, 2017

What We’ll Learn
• Overview and Tour of GitHub
• Terminology
• Working in GitHub
– Project Documentation options
– Issue Tracking
– Version Control
• Integrations with other tools
• Social features

GitHub
Web-based
repository for
software projects
Public GitHub hosts
over 35 million
repositories and has
14 million users.
https://github.com/
Octocat, the GitHub Mascot
(Simon Oxley)

Git is the infrastructure for GitHub.
Distributed version control system for
software development
Developed by Linus Torvalds, creator of Linux.
#1 code management tool, adopted by one
third of software developers

Individuals with a free account:
• Can create public repositories and contribute
to projects.
For a fee:
• Can create private repositories
Organizations can post projects on the public
version of GitHub for free, as well as purchase
GitHub Enterprise for their internal use.
Flickr: Daniel Oines

Contributing in GitHub
Public repositories – contribute
content and comments (or create a
project)
Corporate Public Projects – project
docs, community management
Corporate GitHub Enterprise Projects
(and private repositories) – project
docs, issue tracking, version control of
source documents.
Docs live with the code
Ordered Listocat by Cameron McEfee

Flickr: www.audio-luci-store.it

PROJECT DOCUMENTATION
OPTIONS
Readmes, Wikis, GitHub Pages

Readme
In GitHub repositories, a Readme file is visible
on the home page.
Authored in Markdown, and has the file
extension of .md.

Lightweight markup language that can be
converted to HTML easily.
Originally developed in 2004 by John Gruber,
and has splintered into different variations.
GitHub uses “GitHub Flavored Markdown”
Extra features: syntax highlighting, task lists, and
tables.
Fun stuff: Emoji Cheat Sheet
Useful: Markdown Cheat Sheet

Wikis
Every repository can have one.
Author in Markdown, or one of the other 8 edit
modes.
By default, anyone can edit your wiki, but you
can switch it to read-only.
https://github.com/showcases/projects-with-great-wikis

GitHub Pages
Webpages hosted and published on GitHub.
Authored in Markdown
GitHub provides themes to create a custom look.
You can add your Google Analytics tracking ID to each
of your Pages.
By default, the URL of your GitHub pages will be:
http://[accountName].github.io/[repoName].
GitHub Pages are always public, even if your repository
is private.
https://github.com/showcases/github-pages-examples

Decisions, Decisions
Need to decide:
• How granular issues should be
• How you want to label them
• Your milestones
• Best practices
GitHub issues can be authored in Markdown, so
you can add formatting, create task lists to track
progress, use emojis, and more.

Handy Features
• To reference another issue, enter “#”
The chosen issue will become a link
• Anyone with Collaborator status can
comment. Enter “@” to ping another
collaborator.
• If you believe something is ready to ship, mark
it with the “Ship It Squirrel” emoji (:shipit:)

Docs follow the same
workflow as code
All project collaborators
can review and
contribute.

Version Control with Git
• You can work in the GitHub GUI, strictly on the
command-line using Git commands, with a mixture
of both, or with an app (like GitHub Desktop).
• If using GitHub Enterprise, your company may
develop guidelines you need to follow around the
naming of branches and who should do reviews and
merges — or you may develop them.
• Check out: https://help.github.com/articles/what-is-
a-good-git-workflow/

GitHub Terminology
Repository: The most basic element of GitHub. They're easiest to
imagine as a project's folder. A repository contains all of the
project files (including documentation), and stores each file's
revision history.
Branch: A branch is a parallel version of a repository. It is
contained within the repository, but does not affect the primary
or master branch allowing you to work freely without disrupting
the "live" version.
Fork: A fork is a personal copy of another user's repository that
lives on your account.
From the GitHub Glossary Flickr: MarcoG2012

Commit: A commit, or "revision", is an individual change to a file
(or set of files). It's like when you save a file, except with Git,
every time you save it creates a unique ID (a.k.a. the "hash") that
allows you to keep record of what changes were made when and
by who. Commits usually contain a commit message which is a
brief description of what changes were made.
Pull request: Pull requests are proposed changes to a repository
submitted by a user and accepted or rejected by a repository's
collaborators.
Merge: Merging takes the changes from one branch (in the same
repository or from a fork), and applies them into another.
Collaborator: A collaborator is a person with read and write
access to a repository who has been invited to contribute by the
repository owner.
Contributor: A contributor is someone who has contributed to a
project by having a pull request merged but does not have
collaborator access.

https://guides.github.com/introduction/flow/
and githubflow-online.pdf

File Facts
• Any file that can be read with a text editor can be
opened and edited within GitHub.
• Use a .gitignore file to exclude local files you don’t
want stored in your repo.
• Even though you can open files (such as .dita files) in
GitHub, you may prefer to use your XML editing tool.
• Binary files (images, Word files, etc.) can’t be opened
within GitHub at all.

Storing Binary files in Git
• This blog post gives a good overview of why
storing binary files in Git can be an issue:
https://robinwinslow.uk/2013/06/11/dont-
ever-commit-binary-files-to-git/
• Git LFS is one possible solution: https://git-
lfs.github.com/; git-annex is another:
https://git-annex.branchable.com/
• Or create a custom solution or separate doc
repo.

Integrations with GitHub
• Over 90 productivity tools can be integrated
with GitHub, including Slack.
See https://github.com/integrations.
• GitBook can be used to host and write books,
see https://github.com/integrations/gitbook.

“Follow” people
“Watch” projects
“Star” projects & visit
your “Stars” page Flickr: Antonio Silveira

GitHub is now being used to collaborate on projects
as diverse as Gregorian chants, licensing agreements,
and wedding invitations
Flickr: Lars Plougmann
From Collaborative Coding to Wedding Invitations: GitHub Is Going Mainstream

Contact information:
Nicky Bleiel
nableiel@us.ibm.com
nickybleiel.com

GitHub Workflows for Technical Communication

More Related Content

What's hot

Similar to GitHub Workflows for Technical Communication

More from STC-Philadelphia Metro Chapter

Recently uploaded

GitHub Workflows for Technical Communication