O'Leary - Using GitHub for Enterprise and Open Source Documentation
-
Upload
lavacon -
Category
Presentations & Public Speaking
-
view
109 -
download
0
Transcript of O'Leary - Using GitHub for Enterprise and Open Source Documentation
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