In Flare, source control is the practice of managing file changes by synchronizing them with a copy of your project files on a server. Source control is even useful for single authors because it provides a means for maintaining a constant backup of all project files. For most Flare authors, source control is an integral part of their overall architecture.
It might be tempting for some authoring teams to want to put a Flare project up on a network drive and simply let multiple authors open and work in it. However, this is not recommended. First, working on projects on a remote server, rather than locally on your computer, can result in lag time and poor performance. And perhaps more importantly, this type of work situation can result in conflicts that never get resolved (e.g., two writers work on the same file, and one writer’s changes overwrite the other’s). That is why a source control solution is highly recommended, especially when multiple writers are working in the same project.
[Menu Proxy — Headings — Online — Depth3 ]
Source Control Tools
Source control isn’t built in to Flare, but you can integrate a Flare project with any of the following third-party source control tools:
As an alternative to these source control tools, authors can use MadCap Central, which employs Git behind the scenes.
Central offers a single-bound model, where your projects work directly with Central to manage source control.
Central also offers a dual-bound model. With this model, you can continue to use your third-party source control tool, as well as create a secondary binding to Central. Unless you have a really good reason for using the dual-bound setup, the single-bound model is recommended because it is easier and more streamlined.
Branching
Branching is a feature of some source control tools where you can work on different versions of the same project. It’s a way of engaging in continuous parallel development, in which you can keep your new development separate from the finished documentation. This can be especially helpful when you are working with an Agile methodology. Flare's interface only supports Git branching, and it therefore also supports branching for projects bound to MadCap Central.
Example You might have a master branch, which is a version of your project the last time you published output.
You also might have a release branch of your project, which is a version of your project for the next, upcoming publication of your output.
Then you might have several feature branches, each one where you have a version of your project dedicated to a new feature you’re working on. And when you’re certain that a particular feature will be part of the next release, you merge it into your release branch, and finally into the master branch. Changes can also be merged back into ongoing feature branches so that they have the latest content from other branches.
Pros and Cons of Source Control
|
Pros |
|---|
|
Source control is simply the most efficient way for multiple writers to work on the same project. It allows multiple people to work simultaneously on the same files and merge their changes when needed. You can also use source control to resolve any file conflicts that you might have with other authors. |
|
Even if you are a lone writer, using a source control solution provides a way to have a backup of your project on a server. This is important in case something happens to your computer and you lose all of your local files. |
|
If you bind your project to Central using the single-bound model, the process is very simple with only a few clicks required. |
|
Some source control tools (e.g., Team Foundation Server) have a check in/check out system that helps alleviate file conflicts. |
|
Cons |
|---|
|
Setup can be challenging for some source control tools when you bind them to a Flare project. You probably need to obtain information from your system administrator, and you must enter everything accurately in the Flare interface for the binding to work successfully. |
|
There is a learning curve involved with source control solutions, especially when it comes to resolving file conflicts. Certain file conflicts can happen when writers are working on the same file. This can be frustrating and confusing at times if you are new to source control. This is why it is important to educate yourself on the particular source control tool you are using, and establish internal rules and guidelines for every member of your team to follow. This can help limit the conflicts that occur and make it less daunting when you need to resolve them. |
|
Source control processes can slow down Flare projects as you work in them. A project that is not bound to source control typically runs faster than a project that is using source control. |
What the MadCap Documentation Team Does
We use source control for all of our projects.
Shared
Our main Shared project is single-bound to MadCap Central (with Git behind the scenes). We rely heavily on Git's branching capabilities, employing a workflow system called “GitFlow,” which makes our files and changes much easier to manage. In Flare, we perform most of the basic source control tasks (e.g., committing and synchronizing changes). For some more obscure source control tasks that cannot be done from the Flare interface, we occasionally use Visual Studio or Git Bash.
Documentation Bible
Our Documentation Bible project is also single-bound to MadCap Central. However, we don't require the use of branching like we do for our main Shared project. When authors need to work in the Documentation Bible project, they simply synchronize it with the cloned project on Central.
"Develop" Projects
Our “Develop” projects exist only as a workaround in order to create checklists for specific Git branches on MadCap Central. Checklists are one of the few features where branching is not yet supported on Central. So in order to create checklists associated with files for a specific branch, we need to create these child "Develop" projects. All of the edits in particular branch is first done in the main “Shared” project. Then, we use Global Project Linking to import changes for a specific branch into the child "Develop" project. So when we upload changes to Central from one of these child projects, we are uploading the master branch for that project, but the imported files are actually coming from specific branches via the parent "Shared" project.
Note If you would like more details on the way that the MadCap Documentation Team uses source control—especially branching—you can download this PDF:
https://docs.madcapsoftware.com/doc-team/Source-Control.pdfThis PDF discusses concepts, reasons why we do things a certain way, procedures, daily tasks, and more.
