How to choose the best Git workflow for your organisation

How do you and your team store content or collaborate on documentation projects, and what’s your method of controlling the changes your contributors make?

In modern tech comms, Git repositories have become indispensable tools for managing and collaborating on documentation projects. A repository is a controlled, versioned collection of the project files, and Git is the most popular system in use today for structuring and managing repositories.

Tracking your team’s changes using a Git repository is referred to as source control, and allows for easy versioning, reviewing, and seamless collaboration. Linking to a Git repository is the cornerstone of the docs-as-code approach, but any online documentation project and tool stack can greatly benefit from implementing source control.

Preparation

To start collaborating as a team in a project repository (or repo), you need to do some preparation. An expert can help you plan how your organisation will employ Git to create your content, and coach your contributors on how to use the tools.

One key part of this is the decision on which Git workflow to use in your project. But what is a Git workflow? Interpretations will differ, but it is most commonly stated as a recipe or recommendation for how to use Git to accomplish work in a consistent and productive manner.

If you want to work it out on your own, the Internet is a perfect resource for learning about and comparing Git workflows. However, it takes advanced DocOps knowledge to assess the key factors involved, and decide which workflow best suits your organisation’s unique needs.

At 3di, we’ve successfully managed a variety of complex documentation projects using cutting-edge tools such as MadCap Flare, DITA-based CMS solutions, and Markdown-based Web portal generators. We have tested the best workflows and solutions for small, fast, agile teams, as well as helped corporate customers who needed precisely structured delivery plans.

In this post, we will delve into some of the aspects which help you make an informed choice of Git workflow. Let’s explore these in detail below.

The factors to consider when coming up with your Git workflow can be divided into three pillars: people, processes, and tools.

We’ll use a bit of Git terminology here, so you will need to know some basics if you want to follow along.

People

• Team size: If the number of collaborators is small, your first thought should be to keep things simple and control the number of branches which the team creates.
• Skill level: If your team members are new to Git, it can be a good idea to base your workflow on a limited set of Git commands and operations. You should also consider using a Git tool with a graphical user interface, and check if it suits your workflow of choice. For example, GitHub Desktop doesn’t fully support rebasing branches, which could be an obstacle for some use cases.
• Collaboration with other teams: If your project needs to interface with another project, we recommend understanding the logic and workflows used in the second project, too. For example, if your documentation needs to be published with releases of the product, it may be simplest to co-locate the docs inside the code repository and use the same workflow.

3di Pro tip: Combining teams and projects like this goes beyond the scope of this blog post. In addition to well-designed workflows, you would need to set up pipelines and processes in the DevOps or DocOps platform of your choice, such as GitLab.

Processes

• Project size and complexity: Match the needs of the project with the level of detail used in your workflow and supporting processes.
  For example, if you need to document several co-existing software releases and maintain their documentation, your workflow probably needs to employ concurrent release branches.
• Use of the Agile methodology: Within this framework or other modern project management approaches, such as Kanban, you’re likely to follow a branch-per-task approach and use more granular workflows.
  3di Pro tip: In our experience, larger teams that follow continuous integration (CI) will see many advantages to using task or feature branches.
• Other factors: Consider typical software project stages and checkpoints, for example, a code freeze or integration phase. If these are absent in your software docs or API docs project, why not consider a simple trunk-based workflow?

Tools

• Learning curve: If you want to add terminal-based source control to your current tech stack, you get great flexibility, but also a steep learning curve. GUI-based tools, such as GitHub Desktop or the SourceControl ribbon in MadCap Flare, will helpfully limit the available Git operations, and allow only for certain steps in the workflow. This can make life easier for contributors (and therefore for you!).
  3di Pro tip: Our in-house authors appreciate the reasonable compromise between speed, ease of use, and versatility offered by GitHub Desktop and as a result, it is our standard tool. Although, some of our local nerds choose to unlock the full power of terminal commands, be it in Visual Studio Code, Git Bash or any other command-line interface.
• Ownership and communication: Some tools and platforms provide features which can help you stay clear on who is currently responsible for a change to your documentation as it moves through your workflow.
  For example, GitHub offers Pull requests which can be used to pass ownership of a change through contributors and reviewers, and also provides a convenient place to track feedback and discussion.

Hopefully this provides an introduction to some of the factors you should consider when designing a Git workflow for your organization or documentation project.

As time goes on, our experience at 3di shows that circumstances can change on your project and warrant a fresh start with the way you use Git – it pays to stay on your toes, and above all, keep listening to your users!

The article was authored by Agata Rygielska and edited by Keith Kirkwood.