Skip to content
Olivier CarrèreTechnical writing practice

Which repository for group work?

Concept
Version control

Why folders and shared network drives fall short for collaborative technical writing: concurrent edits overwrite one another and file locking blocks batch changes - problems that version-control systems solve reliably.

, 2 min read

View as Markdown

Definition

Section titled “Definition”

The most commonly used RepositoryThe place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file.View in glossary → for storing computer files is the folder, or directory. While this is perfectly suited for managing files by a single user on their local hard drive, it quickly shows limitations for collaborative work - as detailed in shared network directories.

The situation: two writers, one file

Section titled “The situation: two writers, one file”

Let’s imagine that Alice and Bob open the same version of a file, available on a network drive, in a text editor:

  1. Alice and Bob each open the same version of the file.
  2. They each make different changes to the copy loaded in RAM.
  3. Alice saves her changes first, then Bob.
  4. The next time the file is opened, only Bob’s changes appear in the file.
Concurrent edits to a file on a shared network driveSequence diagram showing Alice and Bob opening the same version of a file, each editing their own copy, then saving one after the other: Alice's changes, saved first, are overwritten by Bob's.Open (copy loaded into RAM)Open (copy loaded into RAM)Edits her copyEdits his copySaveSaveOnly Bob's changes are keptAliceFile on the network driveBob

Concurrent edits: Bob’s changes overwrite Alice’s.

Why it happens

Section titled “Why it happens”

To work on a file, the technical writer uses an application that reads the file from their hard drive and loads a copy into RAM. Modifications are made on this copy. When the technical writer saves their changes, the program overwrites the previous version of the file on the hard drive.

The previous version is therefore permanently deleted unless:

  • the program has created a backup copy. There are then only two versions of the file at any given time: version n and version n-1.
  • the technical writer uses Save As, not Save, to create a new version of the file. The technical writer can then create as many versions as needed, for example by adding the suffix -1, -2, etc., to the file name.

Possible approaches and their consequences

Section titled “Possible approaches and their consequences”
Lock open files
To prevent overwrites, many programs lock open files. They are only available for reading as long as the user modifying them has a copy open in RAM (i.e., until they close it). It is therefore not possible with this system to allow multiple users to work on the same file and make batch modifications across files, such as changing the path of all images.
Do not lock files
If the program used does not lock open files, constant coordination is required between team members.
Use a version management system
Version management systems address these limitations reliably.

Next steps

Section titled “Next steps”