LavaCon

1. Using GitHub for Enterprise and Open
Source Documentation
Lynda O’Leary
LavaCon, May 2017
@olearylynda

2. About me
@olearylynda

3. Agenda
Introduction to Git and GitHub
Adapting your documentation workflow
Contributing to open source documentation
Q&A

4. Environment

5. What do we need?
Small chunks
Topic orientated
Single-source
Various outputs
Technical reviews
Peer reviews
Maintain quality

6. Collaborative Tools
MadCap Flare MadCap Flare
SVN Git
Planning tool

7. Why Git?
Lightweight branching
● Isolate workspace
Decentralized model
● Perform VCS operations with no remote connection.

8. 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

9. 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

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

11. 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/.

12. Terminology
Repository - contains your project files.

14. Fork
A copy of a repository.

15. Branch
Use branches to work on different versions of a repository at one time.

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

17. Commit messages

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

19. Merge
Merges changes into master.

20. 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

21. Clone
Downloads a copy to your local computer.

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

23. GitHub Integrations
Continuous Integration
Communication
Editor

24. Markdown
● Simple format
● .md file
● Text editor - Atom, Sublime
https://guides.github.com/features/mastering-markdown/

25. 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

26. 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

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

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

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

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

31. Using issues
Track updates
Report changes
Suggest improves
Monitor progress

32. Creating labels
Color code
Identify level of difficulty
Include area of work
Add issue type

33. Reviewing Metrics
Who is contributing?

34. Reviewing Metrics
Timeline of commits

35. Reviewing Metrics
Code Frequency and traffic

36. Increasing the feedback cycle
Issues - create and review
Labels - create meaningful names for all levels
@mention - provide clear feedback, comment in conversations
Add to backlog and implement changes

37. 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.

38. Examples of best practice and contributing guides
https://symfony.com/doc/current/contributing/documentation/overview.html
https://help.github.com/articles/setting-guidelines-for-repository-contributors/

39. Cultural Change

40. Continuous Integration/Continuous Delivery
Next steps to ensure quality:
● Automate Builds
● Automate Tests
● Automate Deploy

41. 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/

42. 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

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

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

45. Your GitHub profile is more important than your
LinkedIn profile, to companies you actually want
to work for

46. Your GitHub Profile is your public portfolio

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

48. How to start contributing?
● Find a small project
● Read the Readme file
a. information about the project
b. Contributors Guide
c. Code of Conduct
● Claim the issue
● Edit this page link

49. Communicate with contributors
➔ IRC Cloud
◆ join the project channel
◆ chat to contributors
➔ Twitter
➔ Slack

50. 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

51. FAQs
Where 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?

52. Thank you!
@olearylynda