Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

O'Leary - Using GitHub for Enterprise and Open Source Documentation

286 views

Published on

LavaCon

  • Be the first to comment

  • Be the first to like this

O'Leary - Using GitHub for Enterprise and Open Source Documentation

  1. 1. Using GitHub for Enterprise and Open Source Documentation Lynda O’Leary LavaCon, May 2017 @olearylynda
  2. 2. About me @olearylynda
  3. 3. Agenda Introduction to Git and GitHub Adapting your documentation workflow Contributing to open source documentation Q&A
  4. 4. Environment
  5. 5. What do we need? Small chunks Topic orientated Single-source Various outputs Technical reviews Peer reviews Maintain quality
  6. 6. Collaborative Tools MadCap Flare MadCap Flare SVN Git Planning tool
  7. 7. Why Git? Lightweight branching ● Isolate workspace Decentralized model ● Perform VCS operations with no remote connection.
  8. 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. 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. 10. Why GitHub? ● Fast ● Multiple users ● Built in reviews ● Powerful search ● Secure ● User Management ● Issue tracker ● Integrations
  11. 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. 12. Terminology Repository - contains your project files.
  13. 13. Fork A copy of a repository.
  14. 14. Branch Use branches to work on different versions of a repository at one time.
  15. 15. Commit ● Save changes to your branch ● Small commits ● Shows history of work and commit message ● Commit often ● Commit completed work ● Write good commit messages
  16. 16. Commit messages
  17. 17. Pull Request ● Method of notifying project maintainers about your changes ● Open at any time during development (get discussion started)
  18. 18. Merge Merges changes into master.
  19. 19. 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
  20. 20. Clone Downloads a copy to your local computer.
  21. 21. Useful commands ➔ git status ➔ git log ➔ git blame ➔ git bisect ➔ git checkout <branch> ➔ git branch ➔ git rm <file> ➔ git fetch ➔ git push ➔ git pull
  22. 22. GitHub Integrations Continuous Integration Communication Editor
  23. 23. Markdown ● Simple format ● .md file ● Text editor - Atom, Sublime https://guides.github.com/features/mastering-markdown/
  24. 24. 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
  25. 25. 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
  26. 26. Using branches ● Work in your own workspace without disruption ● Define branch naming ● Short lived ● Branch > tag > roll back
  27. 27. Reviewing content ● @mention ● Never merge your own PR ● Be respectful ● Follow the defined workflow ● Reward people for their work
  28. 28. Publishing your content ● Release tagging ● Discuss a workflow that works for your team ● Automate
  29. 29. Managing your work ● Use gists ● Use project boards ● Add milestones ● Look at metrics
  30. 30. Using issues Track updates Report changes Suggest improves Monitor progress
  31. 31. Creating labels Color code Identify level of difficulty Include area of work Add issue type
  32. 32. Reviewing Metrics Who is contributing?
  33. 33. Reviewing Metrics Timeline of commits
  34. 34. Reviewing Metrics Code Frequency and traffic
  35. 35. 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
  36. 36. 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.
  37. 37. 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/
  38. 38. Cultural Change
  39. 39. Continuous Integration/Continuous Delivery Next steps to ensure quality: ● Automate Builds ● Automate Tests ● Automate Deploy
  40. 40. 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/
  41. 41. 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
  42. 42. Open source is for everyone ➔ Triage ➔ Technical Writers ➔ QA ➔ Community Managers ➔ UX experts ➔ Software Engineers ➔ Recruitment
  43. 43. Benefits of contributing to open source ➔ Visibility to employers ➔ History of your work ➔ Shows you have an interest ➔ Learn new skills
  44. 44. Your GitHub profile is more important than your LinkedIn profile, to companies you actually want to work for
  45. 45. Your GitHub Profile is your public portfolio
  46. 46. Search for a project ➔ Aligns to your interests ➔ Communicate with the community ➔ Read the guidelines ➔ Respect contributors ➔ Volunteer to help
  47. 47. 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
  48. 48. Communicate with contributors ➔ IRC Cloud ◆ join the project channel ◆ chat to contributors ➔ Twitter ➔ Slack
  49. 49. 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
  50. 50. 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?
  51. 51. Thank you! @olearylynda

×