Using GitHub for Enterprise and Open Source Documentation

Lynda O’LearyLavaCon, May 2017

@olearylynda

About me

@olearylynda

AgendaIntroduction to Git and GitHub

Adapting your documentation workflow

Contributing to open source documentation

Q&A

Environment

What do we need?Small chunks

Topic orientated

Single-source

Various outputs

Technical reviews

Peer reviews

Maintain quality

Collaborative Tools

MadCap Flare MadCap Flare

SVN Git

Planning tool

Why Git?Lightweight branching

● Isolate workspace

Decentralized model

● Perform VCS operations with no remote connection.

Git versus Traditional VCS

GIT Traditional VCS

● Snapshot of a miniature filesystem

● Distributed version control system

● Perform commits and merges on your local

● Push changes to central server

● Set of files● Centralized version control

system ● Changes made to each file

over time

Install Git● Command line - all platforms● Desktop client

1. Download Git https://git-scm.com/downloads.2. Set username and email address.3. Authentication - HTTPS/SSH

Why GitHub?● Fast ● Multiple users● Built in reviews● Powerful search● Secure● User Management● Issue tracker● Integrations

GitHub➔ Hosts Git repositories ➔ Central point of collaboration

◆ clone other projects◆ submit pull requests

➔ Area for networking◆ build a profile◆ upload and share projects◆ connect with contributors

➔ Sign-up https://github.com/.

TerminologyRepository - contains your project files.

ForkA copy of a repository.

BranchUse branches to work on different versions of a repository at one time.

Commit● Save changes to your branch● Small commits● Shows history of work and commit message● Commit often● Commit completed work● Write good commit messages

Commit messages

Pull Request● Method of notifying project maintainers about your changes● Open at any time during development (get discussion started)

MergeMerges changes into master.

GitHub Flow➔ Fork the project you want to contribute to➔ Create a branch

◆ your own area◆ changes don’t affect master branch

➔ Add commits◆ changes to your branch (add, edit, or delete a file)◆ history of work and commit message

➔ Open a Pull Request◆ method of notifying project maintainers about your changes◆ open at any time during development (get discussion started)

➔ Discuss and Review PR➔ Merge PR to master

CloneDownloads a copy to your local computer.

Useful commands➔ git status➔ git log➔ git blame➔ git bisect➔ git checkout <branch>➔ git branch➔ git rm <file>➔ git fetch➔ git push➔ git pull

GitHub IntegrationsContinuous Integration

Communication

Editor

Markdown● Simple format● .md file● Text editor - Atom, Sublime

https://guides.github.com/features/mastering-markdown/

What did I learn?● Agree on a workflow● Implement in stages● Collaboration increased● Easier to track issues● Same tools made it easier for reviews● Treated docs like code● Visibility

Storing your content● Repo only for docs● Store docs in with code

○ Standardize docs folder in project

● Include Readme file● Include .gitignore file● Only migrate the content you need● Add wikis to your repo https://github.com/showcases/projects-with-great-wikis

Using branches● Work in your own workspace without disruption● Define branch naming● Short lived● Branch > tag > roll back

Reviewing content● @mention● Never merge your own PR● Be respectful● Follow the defined workflow● Reward people for their work

Publishing your content● Release tagging● Discuss a workflow that works for your team● Automate

Managing your work● Use gists● Use project boards● Add milestones● Look at metrics

Using issuesTrack updates

Report changes

Suggest improves

Monitor progress

Creating labelsColor code

Identify level of difficulty

Include area of work

Add issue type

Reviewing MetricsWho is contributing?

Reviewing MetricsTimeline of commits

Reviewing MetricsCode Frequency and traffic

Increasing the feedback cycleIssues - create and review

Labels - create meaningful names for all levels

@mention - provide clear feedback, comment in conversations

Add to backlog and implement changes

What do we need to improve?Localization - working with siloed teams?

Peer reviews - where to fit in?

Doc workflow - intent to deliver but sometimes fall behind?

Software/doc workflow - alignment to deliver on time.

Examples of best practice and contributing guideshttps://symfony.com/doc/current/contributing/documentation/overview.html

https://help.github.com/articles/setting-guidelines-for-repository-contributors/

Cultural Change

Continuous Integration/Continuous DeliveryNext steps to ensure quality:

● Automate Builds ● Automate Tests● Automate Deploy

GitHub Pages● Static site hosting service● Hosted from your GitHub repo● username.github.io● Select a theme● Add custom domain

More information: https://pages.github.com/

Contributing to open source● Wide variety of projects● Range of tools● Difficult to find easy issues for beginners● New method of communicating● Uncertainty of the process

Open source is for everyone➔ Triage➔ Technical Writers➔ QA➔ Community Managers➔ UX experts➔ Software Engineers➔ Recruitment

Benefits of contributing to open source➔ Visibility to employers➔ History of your work➔ Shows you have an interest➔ Learn new skills

Your GitHub profile is more important than your LinkedIn profile, to companies you actually want

to work for

Your GitHub Profile is your public portfolio

Search for a project➔ Aligns to your interests ➔ Communicate with the community ➔ Read the guidelines➔ Respect contributors➔ Volunteer to help

How to start contributing?● Find a small project● Read the Readme file

a. information about the projectb. Contributors Guidec. Code of Conduct

● Claim the issue ● Edit this page link

Communicate with contributors➔ IRC Cloud

◆ join the project channel◆ chat to contributors

➔ Twitter➔ Slack

Resources➔ Git for All Platforms http://git-scm.com➔ Emoji cheat sheet http://www.emoji-cheat-sheet.com/➔ IRCCloud https://www.irccloud.com➔ GitHub Guides https://guides.github.com/➔ Git cheat sheet

https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf➔ LavaCon Tutorial https://github.com/lyndaoleary/lavacon

FAQsWhere do I add my docs?

When should I delete a branch?

When would you restore a branch?

What is the difference between fork and clone?

What is the difference between clone and download?

What happens if 2 people working on same content?

Can I commit directly to master?

Thank you!

@olearylynda