Shared network directories - unsuitable for group work
Shared network drives are a common but inadequate solution for team documentation collaboration. Learn why they fail and what version-control alternatives work better.
Definition
Section titled “Definition”Files shared by a technical writing team are often stored in a shared directory on the network. Version management systems offer a more robust alternative for collaborative work.
Failure modes
Section titled “Failure modes”Technical writers work directly on shared files. Each weakness of the shared directory has a counterpart in a version management system handling text files:
| Failure mode | Shared network directory | Version management system |
|---|---|---|
| Network failure | Risk of data loss | No risk of data loss |
| Offline work | Limited possibilities | Advanced capabilities |
| Concurrent access | Files locked by the team members who have opened them | Files not locked by the team members who open them |
| Restoration | Directory by directory, from backups often only daily | Very fine-grained, both in time and in workload |
Why backups are not enough
Section titled “Why backups are not enough”Even with frequent backups, directories are not a secure 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 data:
- Coarse granularity. The granularity of the backup is at the directory level, and backups are often only daily.
- Restoration out of the writer’s hands. In the event of data loss, restoration is done directory by directory, not file by file, and involves versions whose age depends on the system administrator, not the technical writer.
- Error-prone searches. Searching through archives is a tedious operation that can lead to errors; without a reliable and easy comparison between several versions of files, the technical writer can easily lose changes they intended to keep while trying to restore others.
Working on a local copy does not solve it
Section titled “Working on a local copy does not solve it”Copying a file from the network to modify it on a personal hard drive and then overwriting the network version with the local version is a risky operation:
- No notification. Team members are not notified if another member is modifying the same file simultaneously, leading to one of the technical writers losing all of their changes. Which repository for group work? walks through a similar scenario.
- Older versions overwrite newer ones. When manually copying files, either via a graphical file manager or from the command line, the technical writer can easily overwrite the most recent version with an older one.
A file synchronization program such as rsync or Unison (the latter being better suited for bidirectional synchronization) from the command line under GNU/Linux or Windows, or a graphical equivalent such as FreeFileSync, is recommended. However, these programs rely on the last modification date of the files.
For a deeper look at how Git manages content rather than files, see the dedicated article.