博客

In this Case Study we are delighted to share Symplectic’s success in using Overleaf to produce high quality, up-to-date, technical documentation for their clients.

Symplectic’s flagship product, Elements, is a Research Information Management System used by institutions to capture, analyse, and showcase research by enhancing its visibility.

The Symplectic team needed a new way to manage and produce technical documentation for their clients. After exploring a number of options, which did not meet their needs, they chose Overleaf because it provided an easy-to-use, flexible and scalable solution they were looking for. Overleaf enabled them to create and maintain complex technical documentation: keeping it up-to-date, which, coupled with Overleaf’s excellent formatting/layout capabilities, delivered an improved service to their clients and end-users.

With Overleaf, the Symplectic team finally had a solution that “stuck” and have been using it since January 2018, with great results.

Andrew Bennet, Senior Developer at Symplectic commented that:

With Overleaf, working with large complex documents is no longer a daunting task. We now have a process for developing technical documentation which has virtually eliminated the time required to properly format and layout documents, allowing us to focus on the creation of the technical content.

— Andrew Bennet, Senior Developer at Symplectic

Overleaf is a collaborative authoring platform, with version control, that is built on top of the powerful and extremely versatile LaTeX document production system. Utilizing the power of LaTeX macros and packages, Symplectic were able to create a tailored authoring environment which they can easily customize to meet current and future documentation requirements. Multiple authors can work together on the same documentation project and utilize LaTeX’s tools to ensure consistency is maintained throughout the final document.

The documentation challenge

High-quality documentation is a key ingredient to the success of any complex or large-scale software project—such as Symplectic Elements—whether that documentation is produced for use by clients or internally by the development team. However, keeping software documentation up-to-date as new features/functionality are introduced, or old ones are deprecated/removed, always presents a range of challenges, not least because it can be time-consuming. Complex or inefficient document-authoring and management tools can be a further burden when ensuring the maintenance of good, up-to-date documentation.

As any software project grows in scale and complexity, it becomes increasingly difficult for any one individual to have sufficient product or technical knowledge/expertise to write all the documentation or content, pointing toward the need for a collaborative approach to document production. Contributions and updates need to be supplied by domain experts across different teams—whether that is new text/images or assisting other team members by answering questions or helping with technical fact-checks. Additionally, marketing, sales and technical support teams need to augment documentation based on customer feedback: such as clarifications, better examples or additional “how to” content.

Finding a new solution to write software documentation

Like many other software companies, Symplectic had tried various documentation tools—in particular, for documentation to accompany their Elements product. Initially, the Symplectic team were writing documentation using Google Docs which of course provides shared access and a good commenting facility. However, they encountered obstacles with trying to keep documents updated and correctly formatted—the team also needed to use XML code snippets, which are difficult to use and maintain in Google Docs. Those difficulties made the documentation increasingly hard to manage which increased the risk of documents becoming out-of-date. A number of other options were considered, including using markdown—similar to the readme pages on GitHub —but it proved difficult to reliably generate suitably-formatted PDFs from markdown-based content.

None of the various solutions that the team tried or tested worked particularly well and maintaining up-to-date documentation remained a labour-intensive activity, which the team were determined to address. They needed an authoring solution that would “stick”: something which everyone would embrace and provided ample scope for customization and configuration to meet current and future requirements.

Overleaf to the rescue: but LaTeX?

In the search for a scalable, collaborative authoring platform which provides flexibility and produces nicely formatted (typeset) output, the Symplectic team decided to try Overleaf which produces typeset documents using the LaTeX document preparation system.

Although they were aware of Overleaf, some team members had initial reservations due to the perceived complexity of LaTeX—which, they thought, might be a barrier for those team members who don’t use it. However, those concerns soon dissipated because Overleaf made using LaTeX very straightforward which quickly resulted in widespread adoption by their team—clearly vital for removing or reducing barriers to document preparation.

For example, users not familiar with LaTeX syntax can use Overleaf’s “Rich Text” mode which provides a word processor-like view of the document.

Andrew Bennet, Senior Developer at Symplectic explained some documentation challenges faced by the team and how Overleaf provided the solution:

One of our main requirements for a documentation solution was to improve the experience of working with snippets of syntax-highlighted code and markup, such as XML, and to make it easier to maintain formatting consistency. We initially attempted to use Markdown, but since it was primarily designed for the Web we found that the tools to generate formatted PDF documents were extremely limited.

With Overleaf, we discovered we could easily use LaTeX packages and define macros tailored to our formatting needs; the editing processes were also significantly simplified by the cloud-based collaborative editing features.

Because Overleaf harnesses the full potential of LaTeX, and compiles typeset documents in real-time as you write, the Symplectic team were able to create and configure a document-production environment tailored to their specific requirements. The result was very high quality typeset documentation, perfectly formatted according to the needs of the product and ready for immediate delivery to their end-users.

Key benefits for Symplectic Elements

General benefits

• Documentation is now much more up-to-date and significantly faster to produce, resulting in the delivery of an enhanced customer service.
• Overleaf’s labelling features facilitated version management of documentation supplied to clients.
• Overleaf’s collaboration tools made it very easy to invite colleagues/teams to work together on the same document—for writing, copyediting/proofreading, fact checking and so forth.
• Large complex documents were easy to manage by splitting the main document into separate files: much easier to navigate—previously, in Google Docs, they had to scroll through a huge document which wasn’t ideal.
• Overleaf made it easy to insert and update code snippets and to create inline XML.
• The Overleaf/LaTeX combination enabled the production of documents with a very high level of consistency—both in formatting/layout and terminology.

Benefits from using LaTeX

• Overleaf made it much easier to start using LaTeX, which enabled new users, completely inexperienced in LaTeX, to very quickly become productive—making contributions and updates to the documentation.
• The power and flexibility of the LaTeX system (such as defining macros, and using associated packages), provide unparalleled flexibility for quickly making global changes to documents—for example, commands to change spacing in the code would update it everywhere, automatically.
• Sophisticated syntax coloring/highlighting features helped to improve document readability and usability for end-users. The excellent typography provided by LaTeX, and wide range of available fonts, was also a definite bonus.
• The ability to define LaTeX commands (macros) greatly eased the task of document maintenance.
• Thanks to LaTeX, linking between document sections was extremely easy and worked really well.

With Overleaf, the Symplectic team finally had a solution that “stuck” and have been using it since January 2018 with great results, resulting in many improvements to their technical documentation workflows with well maintained and up-to-date information now being routinely delivered to their clients.

About Symplectic

Symplectic is a software development and service team specialised in the capture, management and reuse of research information data. Their software is used by many of the world’s leading research institutions and their team are known internationally for their excellent level of service.

About Overleaf

Overleaf brings state of the art, collaborative authoring technology to the world of science, to make it faster and more accessible. Our solutions are designed to make the whole process of writing, editing and publishing scientific and technical papers much quicker and easier for all parties involved. Overleaf enterprise solutions simplify and accelerate the scientific publishing process by keeping the paper in a single central place through its entire lifecycle.

Disclaimer: Overleaf and Symplectic are part of Digital Science.