You already know you should be using source control, but implementing it may sound daunting. In this two-hour workshop, we’ll take an existing MadCap Flare project and bind it to your choice of either a Git or Subversion repository in the cloud, live and in-session.
What Goes Wrong with Language Definitions and How to Improve the Situation
Hands-on with Source Control: Using MadCap Flare with a Cloud Source Control Provider
1. PRESENTED BY
Hands-on with Source Control:
Using Flare with a Cloud Source Control Provider
Paul Pehrson
DocGuy Training | @docguy | www.docguy.training
2. About Me
• (Ab)using Flare for 10
years
• Full time technical writer
at Venafi
• Part time Flare consultant
and trainer at DocGuy
Training
4. What benefits does source control give me?
• Project is backed up. Forever.
• Multiple writers, one project.
• Version tracking that matches your product.
• UNDO! Oh Crap!
(i.e. Why do I care?)
6. Step 1: Pick a Source Control Provider
• Flare connects with the following source control
providers natively:
– Subversion (SVN)
– GIT
– Microsoft Team Foundation Server (TFS)
– Microsoft Visual Source Save (VSS)
– Perforce
7. Step 2: Figure Out Where Your Database Is
• Dev group?
• Cloud provider
• Set up your own
8. Step 3: Configure CloudForge
1. Go to www.cloudforge.com
2. Click Login
3. Enter the username and password assigned to you
4. Create a Project
5. Choose SVN (to minimize questions today)
9. Step 4: Configure Flare
1. Visit
http://www.docguy.training/MW2016/SampleSourceCont
rol.flprjzip
2. Locate the download on your computer and double-click
it to open it in Flare
3. Open Project Properties
4. On Source Control tab, Bind Project…
5. Use options from CloudForge, and click Okay.
10.
11.
12. Step 5: Day-to-Day Operations
• Update the Project
• Modify files
• Check in files
• Lock a file
• Source Control settings in Flare
14. How GIT is different
• Local commits vs. pushing to the server
• Better option if you work offline frequently
• Better for smaller doc teams (fewer merge conflicts)
• Doesn’t allow you to ‘lock’ files, which makes for more
merge conflict potential than SVN
What is source control?
A way to back up your project. For this reason alone you should be using Source Control. A lone writer on their own project should use source control, just for the backup.
A way to allow multiple people to work on the same project at the same time. Think about this one. What are your options for working with multiple writers on a project? Work on the same project on a network drive?
A way to track versions of your help project that correspond to the product releases. At any point, I can go back to version 4.1.1, and see the help system as it existed at that moment. I can even branch off my help and create updates for the 4.1.1 version without interrupting my current project state.
A way to go back to undo a disastrous change you didn’t realize you were making. You’ve had those moments, right? I did a global find-and-replace in source code that completely trashed my project. Topics wouldn’t open I couldn’t do anything. But because I had the project in source control, I easily reverted my project to the last good state. It took me longer to cause the damage than it did to clean it up.
Image Credit: Flicker – CC-BY/SA - https://www.flickr.com/photos/23157779@N07/8229390510
So where do we begin?
How do I pick?
If you are in a software development environment, ask “What do my engineers use?” and then use that. You’ll have people in your organization who understand that tool and use it on a daily basis. You might even be able to utilize their source control database and check your content into the same database they are using.
If you don’t have a team-supported tool, then you can pick depending on if you have any experience with a specific tool, or you could consult the position of Venus in relation to Jupiter (just kidding).
From the topics I see in the MadCap forums, I would guess most users who use the forums use either SVN or GIT. Since these are widely used, you’re likely to find great support both in the MadCap forums as well as on other support sites, should you need support.
My experience is limited to SVN and GIT in Flare.
