Maxim Kulagin, Head of Technical Support, C3D Labs, talks about the company’s documentation formats and authoring tools.
Let's talk about documentation authoring: what we had, what we are doing now, and what we are striving for. With our diverse components and delivery options, we use many different document formats (рис. 1).
Fig. 1. Available document formats
The changes.txt comes with the installation package. It is a plain text file with a list of changes. All documentation is published on our website. The changes.txt file is available on the For Developers page.
We create most documents with the Doxygen technology. It generates documents automatically from the comments in
The documentation for the C3D Web Vision component is a special case, as this component uses different technologies and has a different structure. For it, we use Sphinx. The source files are in the Markdown format. The site is auto-generated from these files.
Finally, detailed documentation is provided in the PDF format. It contains extended descriptions: how to work with the components; available classes of surfaces and topological objects, how converters function, etc. This documentation is the most difficult to modify. Initially, we create it in ODF (OpenDocumentFormat), an open analog of the DOC format. In this format, we can make visually appealing, image-rich documents. However, the technology has a number of issues.
Let's call it "DOC as DOC". What are the real-life problems with it? First, the contents, formatting, and images are all stored in the same file. It is quite difficult to separate these components. Another problem is challenging collaboration. Our documentation is extensive and covers almost all C3D Toolkit components. When multiple developers make changes simultaneously, synchronization becomes a problem. It is a general issue for any DOC format documents.
This format is not a plain text file. It is a zip file with XML, metadata, and images inside. Sharing it between multiple users is not easy; special tools are required.
Another problem is that this format is difficult to convert to formats other than PDF. PDF is the easiest way to get a printable copy However, there are issues with the PDF format as well. The key reason is using ODF rather than DOC, which often leads to broken formatting. You change just one line at the beginning, and get a messy text in the second half of the document.
An increasingly popular alternative approach is "Doc as Code" (рис. 2). Since we are software developers, it would be logical to treat documentation as source code. The code is stored in a version control system (Git in our case). The source files are plain text files. They are easy to read, compare, and edit with the simplest tools. Git has a built-in utility for comparing such files.
Fig. 2. “DOC as Code” technology
Then we generate a final document in the format we need. The document generation procedure is easily customizable and can be run automatically. Just as we compile the source code, we compile documents in different formats using appropriate tools. This approach fits the software development paradigm much better and avoids a lot of documentation-related problems. Fewer problems mean simpler, better processes. Besides, the documentation is always kept up-to-date.
There are many tools for this. The list of available solutions is almost endless. One of them is Sphinx. Each of these has both advantages and disadvantages. We have certain requirements for the system. These include plain text format for source documentation, support for embedded images, and separation of formatting from content. Another important point is support for complex math equations, as we use them in our documents. Creating equations with conventional tools is tricky.
Out of many solutions, our development teams voted for LaTeX. It is our final decision, and we are developing documents in this very format. An advantage is that it is open source, free software. Certainly, the source files are in plain text format.
The LaTeX format originates from the academic community. It supports complex mathematical expressions, which is extremely important to us. A final document can contain images, support auto numbering, and have built-in subroutines to auto-generate some document elements (numbering of pages, sections, paragraphs, figures, etc.)
LaTeX also separates formatting and text content into different files, which is very convenient because you can set up different formatting templates and get multiple output options. Another significant factor is that this format is widely used by physicists and mathematicians, and we have a lot of them on the team.
We receive many requests to make our documentation clearer, more complete, more up-to-date, and richer in examples. That’s why we have hired a new employee for the technical support team — a technical writer responsible for our documentation.
The transition from ODT to TeX is almost complete. There are just a few outstanding tasks related to formatting and continuous integration (CI). We’ve strived to separate content and formatting. We automate everything that can be automated to minimize human error. Setting up CI to auto-generate PDFs is already in progress.
We want to generate not only PDFs, but also a user-friendly web version. Today, users are accustomed to the quick search bar in any document. We plan to implement a feature where the user can search for something like "how to perform a Boolean operation in the C3D kernel," and the system will take them directly to the page describing the relevant function.
Once we complete the technical setup, we will focus on the content by adding many new examples, which are currently being collected and systematized. With a dedicated employee and a proper authoring process in place, we can keep the documents up-to-date. The expected result is a complete, detailed, and regularly updated description of the kernel features, available in many formats, easy to read and search. This will make it easier to learn our software and accelerate your work with the C3D Toolkit components.
Maxim Kulagin,
Head of Technical Support,
C3D Labs
