Case Study: CFEngine gets a document collaboration boost with Overleaf

“Overleaf allowed us to move to a totally different level, previously collaboration was done on plain text level so we would have to move the document into GitHub. There was no real-time collaboration and it was very cumbersome. Now we have this. We can collaborate on the almost final version of the document very close to the produced PDF.”

This is a guest blog post written by Vratislav Podzimek with contributions from Ole Herman Elgesem, Nick Anderson and Cody Valle.

Background

Northern.tech has a mission to secure the world’s connected devices with its CFEngine and Mender.io products. CFEngine is a robust and secure solution designed to provide visibility over key IT infrastructure, automate key configuration tasks and maintain the required standards of security and compliance over the IT assets. Mender.io provides secure, risk tolerant and efficient over-the-air updates for all device software.

Open source is at the heart of Northern.tech's development culture, and allows for flexible and highly dynamic development and integrations that help customers avoid vendor lock-in and benefit from the wisdom of a community of domain experts. Having an open way to collaborate and share decision support information with the community of users is also very important. For this reason, the team at CFEngine publishes highly informative white papers written to meet the needs of their audience.

The CFEngine product development, product management and community team used Overleaf to help improve the collaboration surrounding the creation of a very important technical white paper. The white paper compared CFEngine to Ansible in the ways both solutions address the scalability challenge in server configuration.

The white paper was co-authored by Vratislav Podzimek, Ole Elgesem, Nick Anderson and Cody Valle. Vratislav describes the process of authoring this white paper on behalf of the team.

First phase - writing in plain text

The first draft of the white paper was written in org-mode.

Vratislav explains that LaTeX, as a language, can appear very technical, especially to a new user. He says “because of the complexity and to get a clean start on the writing, it makes sense to start with soft markup, to work with a format that does not require you to write complex sequences into the document."

So Vratislav felt for the team’s purpose, it was easier to start with the document in a plain text format with no markup, and then write the text body. The content was actually written before LaTeX or Overleaf was used in this case. Vratislav does qualify this by saying that Overleaf could have been used at this early stage. “The visual editor in Overleaf would work in a similar way as Emacs with org-mode.”

Second phase - polishing and collaboration

In the second stage of the project, the plain text with org-mode markup was exported into a LaTeX document. In Overleaf you create a new project and you can get the basic structure. In Vratislav's words: “The plain text was converted to LaTeX locally, body of the text written, then some modifications and polishing, then we uploaded the LaTeX document to Overleaf.”

At this point Vratislav switched to Overleaf and made minor changes from this point onwards. He found Overleaf to be very useful: “The cooperation with other team members was great, other team members, Cody, Ole and Nick, were able to edit the same document, comment on individual lines, make suggestions that could be accepted or rejected. It was perfect for polishing the draft into a final document.”

Vratislav continues to say that If he did this without Overleaf, each team member would have had to install LaTeX on each machine and then get a special template. “This is a great advantage of Overleaf, making changes, and getting instant feedback through the web user interface.”

Vratislav goes on to say that Overleaf is on par with Google Docs for general document editing and collaboration. Furthermore, “having the same functionality for a LaTeX document is just great and you see the PDF result next to the source, you can see the differences and the changes.”

The CFEngine white paper was a basic document with charts. The input data for the charts came from logs that were long and noisy so the team had to clean these up separately. Different tools were used to create the charts by different team members (GNU plot) and (Python-based library). Flat images were uploaded into Overleaf.

On a new level

The overall team of Vratislav, Nick, Ole and Cody has this to say of their experience of using Overleaf:

“Overleaf allowed us to move to a totally different level, previously collaboration was done on plain text level so we would have to move the document into GitHub. There was no real-time collaboration and it was very cumbersome. Now we have this. We can collaborate on the almost final version of the document very close to the produced PDF."

Nick had a product improvement suggestion for the Overleaf team. He would like to see the integration of org-mode for soft markup into Overleaf. This would, Nick believes, make mark up very easy and non disturbing. This would be appreciated by the more technical audiences.

Ole also said he benefited greatly from the Overleaf template. “You do a search on Google and you end up on the Overleaf template gallery and guides anyway!”