DocFX + Gitea + “Ethos”

As the code base increases, any company begins to feel the need to organize disparate documentation, in other words, to create its own “knowledge base”. As the term itself implies, we are talking about a structured storage of information, and there are a great many ways to organize it. And here it’s worth thinking about who needs a knowledge base and why, because not only the choice of a specific technology, but also the very architecture of the future service will depend on the answers to these questions.

Who needs it and why?

Let's start with the question “to whom”. It is obvious that the average user of the system, its administrator and developer need different information. Moreover, there are technical nuances that ordinary users should not know about at all, for example, data about the customers’ server infrastructure. Accordingly, you need to either limit access to sections of the knowledge base, or even create several isolated storages.

Having decided on the target audience of the knowledge base, you can move on to setting tasks. In our case they looked like this:

1. Reduce the time spent searching for the necessary information by experienced developers.

2. To optimize the training of new developers, that is, on the one hand, to reduce the time to master the necessary knowledge, and on the other, to “unload” experienced colleagues who have until now spent a lot of time explaining the “basic” to each newcomer.

3. Free technical support from solving typical problems of installing and configuring software by describing the relevant processes.

4. Automate the documentation of new code as much as possible.

5. Provide technical writers with instant access to all versions of all documents for each of the company's contracts.

In addition, several more conditions had to be met:

• to eliminate risks from using third-party proprietary software, all tools used must be either open source or proprietary;

• descriptions of methods should be automatically generated from the code;

• all documentation should be easily updated.

First there was a code

Based on the above, we have the following structure of the knowledge base:

The role of the main hub for all employees is played by the repository storage, deployed on its own servers using the Gitea web application. Each of the repositories, along with the code, includes a set of wiki pages containing internal developer documentation: standards for writing code, server settings, instructions for assembling and deploying projects, etc. – in a word, information not intended for a wide audience.

Another source of internal documentation is the code itself, or rather, comments added by technical writers to the source files describing the methods. Such descriptions are standardized and formatted using set of XML tags according to the following plan:

1. method function;

2. description of parameters;

3. return value;

4. examples of using.

This is done not only to ensure uniform documentation, but also so that when building the project in Visual Studio, the C# compiler “packs” the necessary comments into separate XML files (in the MSBuild settings, the GenerateDocumentationFile property must be set to true). And web pages will also be automatically generated from these files.

DocFX: usage scenarios

DocFX, a static website generator with open source. To operate, the application requires .NET SDK 6.0 installed; it runs also under Linux and does not require complex configuration. In our case, customization involved creating your own template for displaying web pages. To do this, we added to the project a folder with CSS files, an extension for the Lunr library that allows searching in Russian, and also edited token.json, adding a Russian translation for the main headings. After that, all that remained was to specify the required paths in docfx.json – and the generator was ready to work.

Its functionality, however, is not limited to “pulling out” comments from the text. DocFX in capable hands is a convenient tool for creating multi-page documentation sites that support a complex structure of sections and subsections, various navigation elements, but most importantly, are easily scalable and updated.

Since texts for DocFX are written in Markdown markup, and their structure is specified in special table of contents files in YAML format, it is convenient to work with documentation as code (Docs as Code). In practice, this means that a technical writer makes changes to his section, after which he “commits” the changes to a specially created Git repository, where they become available to all his colleagues. When changes accumulate, the current version of the project is “fed” to DocFX, and as a result we get a ready-made multi-page page, which can only be uploaded to the hosting.

It is clear that in this case we are already talking about documentation aimed at a wide audience. Along with descriptions of methods, the site publishes and regularly updates manuals for installing and configuring the system, scenarios for working with its individual modules, a description of all database tables and connections between them, that is, everything that a user and administrator may need.

From archive to ERP system

So, now in our knowledge base there is documentation for external users and for developers – all that remains is to decide how we will store the documentation that we write for customers.

In principle, we could have created a separate repository for this, but we decided to do otherwise. Firstly, customers receive almost all documents from us in MS Word format, which is not very convenient to work with in Git. Secondly, not all of our technical writers work with Git, but all of them work with Ethos, our main product, which is a platform for creating ERP systems.

Based on it, in a couple of hours, the developers put together a configuration that made it possible, firstly, to systematize our entire archive, organizing all the documents into the necessary folders, and secondly, to maintain the versioning of added files. Now we not only know who and when added a new version of a particular design solution or instruction, but we can compare the texts of two versions directly in the system to see the changes.

So, we've taken a quick look at all the key elements of our knowledge base. Despite the fact that it took on the described form relatively recently, we already had the opportunity to evaluate its advantages. The most obvious of them is the acceleration of “onboarding” of new employees, who became involved in solving combat missions already in the second or third week of work (previously this took at least a month). Moreover, some of them even managed to be listed on the pages of the corporate Wiki. The effect of “auto-commenting” of the source code is more difficult to assess, but there is no doubt about the necessity of this enterprise, especially since the requirement for a detailed description of all classes and methods in the documentation in some cases is directly stated in the technical specifications.

In conclusion, we emphasize once again that the described system is only one of many options for implementing a knowledge base. Along with DocFX, at least Sandcastle and Doxygen can work only with XML comments in code, and there are a great variety of tools for structured documentation storage with support for versioning.

It is also obvious that the considered configuration is still far from complete. Our immediate plans are to turn the project documentation repository into a full-fledged technical information management system with its own role model, formalized business processes, statistical and analytical tools, etc., but that will be a completely different story.