O'Leary - Using GitHub for Enterprise and Open Source Documentation
2 likes689 views
- The document discusses using Git and GitHub for collaborative documentation workflows, including adapting documentation processes, contributing to open source documentation, and key Git and GitHub concepts and terminology. - It provides an overview of GitHub's features for documentation including hosting documentation repositories, facilitating peer review via pull requests, and integrating with other tools. - The presenter shares lessons learned from their experience including treating documentation like code, increasing visibility and feedback, and tips for contributing to open source projects.
O'Leary - Using GitHub for Enterprise and Open Source Documentation
- 1. Using GitHub for Enterprise and Open Source Documentation Lynda O’Leary LavaCon, May 2017 @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
- 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?