Skip to content
Topos Uranos
English

Writing as a team

Summary

This lesson teaches how several authors can write one document without losing work or mixing up versions. It explains why exchanging versions by e-mail fails and why a plain-text source makes it possible to compare and merge changes line by line; it presents Overleaf as a shared online editor, with project invitations, simultaneous editing, comments, track changes, the history with its labelled versions, the choice of LuaLaTeX and the upload of a local project; it teaches the minimal Git workflow for a LaTeX project, with its .gitignore file, the practice of writing one sentence per line and the resolution of a conflict in a .tex file, using real output from a test repository; it describes Overleaf's Git integration and its GitHub synchronization; it gathers the conventions a team should agree on; and it ends with latexdiff, which produces a PDF with the changes between two versions marked.

Learning objectives

  1. Explain why a plain-text source makes it possible to compare and merge the work of several authors, and why a word-processor file does not allow it in the same way.
  2. Share an Overleaf project with the right permission, comment, review with track changes and recover an earlier version from the history.
  3. Manage a LaTeX project with Git: initialize the repository, commit changes, read the history and the differences, and synchronize it with a remote.
  4. Write a .gitignore that excludes the auxiliary files without excluding anything the document needs.
  5. Predict when two simultaneous changes produce a conflict, and resolve it in a .tex file, checking afterwards that the document compiles and says what it should.
  6. Agree as a team on a preamble, a bibliographic database, a division into files and a labelling convention, and use latexdiff to produce a PDF that shows the changes between two versions.

Why writing together is hard

The most common way of writing as a team is also the most fragile: one author sends the file by e-mail, another corrects it and sends it back under a new name, and after a few weeks the folder contains final-report.docx, final-report-v2.docx and final-report-revised-ana.docx. If two authors worked at the same time on the same version, someone has to carry the changes of one over to the other's file by hand, and whatever is forgotten in that transfer is lost without anyone noticing. The word processor does not help with the comparison, because its file is not readable text but a compressed package that mixes the content with the formatting; it does have comparison tools, but they cannot automatically merge two independent lines of work.

A LaTeX source is a different matter: it is plain text, which any program can read line by line. Two operations follow from this that are not at hand with a word processor. The first is the difference (diff): given two versions of a file, a program states exactly which lines were removed and which were added. The second is the merge: given two sets of changes made to the same version, a program combines them on its own when they affect different places in the file, and asks the author to step in only when both touched the same place. For these operations to be useful, however, some organization is also needed: a common place where the current version lives, and a record of who changed what and when. This lesson presents the two ways of achieving it that the course uses: Overleaf, which solves the problem in the browser, and Git, which solves it on each author's computer, with Texmaker as the editor.