In this guest post by Dee Vincent-Day, Technical Author at Piksel, she describes her experience of integrating Git and her existing MadCap Flare projects, and the benefits she’s experienced along the way.
When I joined Piksel in early 2016, I took over management of two MadCap Flare projects. One project was stored in a SVN version control system and the other was on the local machine pending implementation of GitLab. Part of my brief was to set both projects up with GIT repositories in our GitLab system. For anyone that’s going through a similar implementation, or is preparing to do so, here’s a couple of key observations that you should keep in mind:
Understanding the Learning Curve
I knew I had a lot of work ahead of me when I embarked on this project; I had not used Git for source control before. Previous companies I had worked with used SharePoint and Visual Studio, which were different to the Git process. With Git, you set up the repository on the server and then you connect or bind your project folder to the repository. At this stage, I would recommend that you download the Flare Source Control documentation for Git. It proved to be a valuable resource, and I found everything worked exactly as described.
Working with Teams
Before getting started, it’s important to take some time to think about who is affected by the integration. I work as a sole technical author, which means following a different process to a team of writers. However, every technical authoring environment is different, with various stakeholders and key personnel that may be involved. Therefore, you will need to think about this and plan before rushing in to set it up. If you have a team of writers, may also want to learn more about using Flare with Git. There are other features, such as merging changes from more than one author, which are specific to writing teams. You can find information relating to these features in the Source Control documentation.
Getting Started
For sole authors with little experience of Git, the best piece of advice I can give you is to get yourself set up with a repository per project as recommended in the documentation and to make sure you have a good understanding of how Git manages your changes. If you do this your implementation will run smoothly.
We started by setting up two repositories on the GitLab server. I then followed the instructions in the documentation for connecting my two projects to the remote repositories on the GitLab server. This is known as binding the project to the repository. Once set up, I read the section about using the source control tools in the documentation. It was this part of the documentation where I learned about how Git handles changes and what you needed to do for it to work effectively.
Working with Git
As you add and edit files in Flare, you work locally in your project folder; a list of modified and new files displays in the Source Control Explorer. When you have completed a batch of edits, commit them to the repository. You can add a message to each commit to help identify the content. Committing moves your changes into your local Git repository. Every so often, you then need to push your changes to the remote repository.
Benefits of Integration
The Ability to Revert Changes
After integrating Git with my MadCap Flare projects, one of the immediate benefits was the ability to “Revert” changes. If you go and make some changes then decide you do not want them, you can revert to the previously committed version of the file. You can revert a single file; right click the filename in the Source Control Explorer and select Revert from the context menu. You can also revert all the files shown in the Source Control Explorer by clicking the Revert button above the comment field.
This is a powerful feature, which allows me to experiment with new skin and style settings locally before committing the changes to the repository. If I do not like the results, I can easily revert to the previously committed version.
The Remote Repository
As mentioned earlier, periodically you need to push the commits stored locally to the remote repository (which in my case, was on our GitLab server). This was a great way to provide a sense of security, as it enables you to protect your data and recover from disasters.
As seen below, the Push button is located on the Source Control tab. You do not need to do this every time you commit; I tend to make a few changes and build the project. I check the changes and if everything works as planned, I push the commits to the remote repository. How you handle this is determined by you.
I no longer worry about losing data any more, nor do I worry about modifying skins, targets or stylesheets. If something does not work, I revert to the previous committed version and try a different tactic. In the event of a hard drive failure, I can recover my work from the remote repository.
Ease of Publishing
Our implementation team deploys software and documentation updates from Git repositories. When I publish the help, I publish to the documentation deployment repository and notify the deployment team that the content is authorised for publication. I currently publish five different versions into this repository for different product implementations and customers. An automated system detects the repository has changed and alerts the deployment team. The deployment team then push my content through the deployment pipeline and out to the twenty servers that serve our customers worldwide.
Final Thoughts
The Flare source control forums have been a source of inspiration, with posts that offer some insights into other ways of using Git in different authoring environments. At first I did not understand the forum discussions, but with my newfound personal experience, I now can give my insight to others in the same position as me.
I have learned a lot during my adventures, primarily on setting up repositories and the day-to-day operation of Git within the Flare/Git integration. It was a steep learning curve that has encouraged me to move forward and learn more about Git and source control in general. Ultimately, combining Flare with Git provides me with a more secure working environment and, with the help of the deployment team, an easy route to publishing content to our customers.
Want to explore the source control features in MadCap Flare for yourself? Get started with a free 30-day trial, complete with access to our dedicated support team.
