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.
Version Control, Writers,
and Workflows
Using development processes and tools to swim with the
current, not against it
Ric...
Share Your Experience
WhyMe?
Mathematician . . . Developer . . . Marketer . . . 20+ years a tech writer.
Writers andDevelopers Use Similar Processes – SharingTools CanHelp
Word People
Doc Plan
Code People
Architecture
Planners,...
VCS Repositories Help You Control Files
•Version control system (VCS) repositories (Git, Subversion, Perforce, and others)...
Repository Workflow
1. Maintain a local copy.
2. Keep it in sync with the master.
3. Make your changes and test them local...
Merging Is Not a Big Deal For Docs
•Merging is putting your changes into a changed master copy.
•Most changes (in text fil...
Merging Workflow
1. Check out the file.
2. Make changes.
3. Check it in.
4. If the VCS sees a conflict, use its tools to r...
VCS Repositories Are Central or
Distributed
•Every repo enables checking files in and out and keeps history.
•A central re...
Easy Branching Makes Git Special
•Branching has low overhead.
•Branching enables all repo ops, but keeps changes separate....
Pull Requests are Git’s Review Process
•Git branches enable you to develop independently.
•A pull request says, “please pu...
Git Branching Workflow
1. Create a branch & track it on the origin repo.
2. Make and test changes locally.
3. Sync local w...
Aside: DITA for Small (Impecunious)
Teams
Eliot Kimber, author of DITA for Practitioners, suggests using
•Git for managing...
Tracking Issues Requires an Issue Tracker
•Software systems and their documentation are complex. Keeping track of details ...
Issue Tracking Workflow
1. Someone reports an issue.
2. People comment.
3. Someone (or some process) assigns the issue to ...
Be Part of the Team
•Understand the process you’re part of – even if you don’t seem to be part of it.
• Inhabit the commun...
Useful References
Atlassian Git Tutorials: www.atlassian.com/git/tutorials
Perforce tutorials: www.perforce.com/resources/...
Upcoming SlideShare
Loading in …5
×

Version Control, Writers, and Workflows

1,566 views

Published on

This is a presentation that Richard Mateosian gave to the STC-Silicon Valley chapter in November 2015. To learn more, see http://www.stc-siliconvalley.org.

Published in: Software
  • Be the first to comment

Version Control, Writers, and Workflows

  1. 1. Version Control, Writers, and Workflows Using development processes and tools to swim with the current, not against it Richard Mateosian STC-SV November 16, 2015
  2. 2. Share Your Experience
  3. 3. WhyMe? Mathematician . . . Developer . . . Marketer . . . 20+ years a tech writer.
  4. 4. Writers andDevelopers Use Similar Processes – SharingTools CanHelp Word People Doc Plan Code People Architecture Planners, marketers, interaction designers User Interface Version Control Repository Issue Tracker Product Customers Topics S/W Components Testable PDF, help, website Testable SaaS, download, DVD Support Ad hoc reviewers QA Build Build Iterate indefinitely between the lines Writers Developers
  5. 5. VCS Repositories Help You Control Files •Version control system (VCS) repositories (Git, Subversion, Perforce, and others) keep track of current and old versions of your files. •Projects keep track of related files: generally the sources for building software packages or documents. Master and other branches help manage complexity. •You can check files out, check them in, merge, compare versions. •Repos integrate with other tools. They handle text best (for diffs and merges), but they don’t understand contents or do CCM (component content management).
  6. 6. Repository Workflow 1. Maintain a local copy. 2. Keep it in sync with the master. 3. Make your changes and test them locally. 4. Commit them to the master. Share Your Experience.
  7. 7. Merging Is Not a Big Deal For Docs •Merging is putting your changes into a changed master copy. •Most changes (in text files) don’t conflict, so most VCSs default to optimistic locking – checking out a file doesn’t prevent others from changing it while you are. •Every VCS has tools to handle conflicts; if it can’t resolve them, it asks you to do it.
  8. 8. Merging Workflow 1. Check out the file. 2. Make changes. 3. Check it in. 4. If the VCS sees a conflict, use its tools to resolve it. Share Your Experience.
  9. 9. VCS Repositories Are Central or Distributed •Every repo enables checking files in and out and keeps history. •A central repo (Perforce, Subversion) uses a master server. You must be connected to the master to perform repo operations. •A distributed repo (Git) replicates the origin repo on your machine. Every machine is potentially the master. You can perform repo operations while disconnected from the origin server. •Git is powerful but not user friendly. •GitHub supports using Git for your projects. Many open source projects use it.
  10. 10. Easy Branching Makes Git Special •Branching has low overhead. •Branching enables all repo ops, but keeps changes separate. •Pull request provides review mechanism. •Pull operation merges changes into main branch.
  11. 11. Pull Requests are Git’s Review Process •Git branches enable you to develop independently. •A pull request says, “please pull my branch into the master.” •GitHub manages review comments and responses.
  12. 12. Git Branching Workflow 1. Create a branch & track it on the origin repo. 2. Make and test changes locally. 3. Sync local with origin & issue a pull request. 4. Submitter and reviewers interact until everyone says LGTM (looks good to me). 5. An authorized user (could be you) merges your branch into the master. 6. You delete your branch. Share Your Experience.
  13. 13. Aside: DITA for Small (Impecunious) Teams Eliot Kimber, author of DITA for Practitioners, suggests using •Git for managing content. •DITA Open Toolkit for generating output. •Jenkins (was Hudson) for automating processing. •oXygenXML for editing and producing output locally. Links: drmacros-xml-rants.blogspot.com/2014/01/dita-without-cms-tools-for-small- teams.html, www.dita-for-small-teams.org, www.dita-ot.org, jenkins-ci.org, www.oxygenxml.com Share Your Experience.
  14. 14. Tracking Issues Requires an Issue Tracker •Software systems and their documentation are complex. Keeping track of details is essential. •Issue trackers (JIRA, Bugzilla, and dozens of others) keep and organize information about tasks, defects, and the conversations that arise around them. •Trackers have different slants: general purpose, software development, customer tickets, and so forth. •Many trackers integrate with other tools.
  15. 15. Issue Tracking Workflow 1. Someone reports an issue. 2. People comment. 3. Someone (or some process) assigns the issue to you. 4. You make changes and others review and comment. 5. Designated reviewer closes the issue. Share Your Experience.
  16. 16. Be Part of the Team •Understand the process you’re part of – even if you don’t seem to be part of it. • Inhabit the communication spaces: online chat, project wiki, relevant email lists, issue tracker, even the code if necessary. •Understand tribal customs: use the communication spaces the way others use them. •Take charge of doc review: make it efficient. Don’t waste developers’ time. Share Your Experience.
  17. 17. Useful References Atlassian Git Tutorials: www.atlassian.com/git/tutorials Perforce tutorials: www.perforce.com/resources/tutorials Subversion docs: svnbook.red-bean.com Wikipedia on issue tracking: en.wikipedia.org/wiki/Issue_tracking_system JIRA docs: confluence.atlassian.com/jira/jira-documentation-1556.html Bugzilla docs: bmo.readthedocs.org/en/latest Great book on team communication: Scott Berkun's The Year Without Pants Questions, comments, or corrections: xrmxrm@gmail.com Share your references.

×