Why Git Is A Great Documentation Management Tool

Sometimes not only documentation but also the process of working on it may be critical. For example, in the case of projects, the lion’s share of the work is related to preparing documentation, and the wrong process may lead to errors and even loss of information, and, consequently, loss of time and benefits. But even if this topic is not central to your work, the right process can still improve the quality of the document and save you time.

The approach outlined here has a low entry threshold. Technically, tomorrow you can start working in a new way.

Task definition

You need to create a document or a set of documents. Perhaps this is project documentation or your network logging, or something simpler. For example, you need to describe the processes inside the company or your department. In general, we are talking about any document or set of documents containing text, figures, tables… Let’s complicate the task by the fact that:

This involves joint work, as well as the efforts of a group or several groups of employees
As a result, you want to have a document in a certain format, having corporate style attributes, and created according to a certain template. To be specific, let’s consider it as MS Word (.docx)

10 years ago, the approach would have been quite unambiguous: we would have created an MS Word document or documents and somehow organized editing.

This approach is still valid. It is even used by large integrators when creating project documentation. However, it is intuitively clear that if your work on a document is long-term, intensive, and includes many edits and discussions, this approach is not quite convenient.

Example

I was quite acutely aware of this problem while working for a large integrator. The process of changing the project documentation was as follows:

The engineer downloads the latest version of an MS Word (.docx) document
Changes its name
Makes edits in track mode
Sends the document with edits to the architect
Also sends a list of all fixes with comments
The architect analyzes the changes
If everything is fine, he copies these changes to the latest version file, changes the version, and uploads it to a shared resource
If there are any comments, a discussion is initiated (email or meetings)
A consensus is reached
Go to paragraphs 3–9

Until the work was intense, it somehow worked. But at some point, this process became the bottleneck of the whole project, which led to problems. The point is that things get worse as soon as changes are made frequently and simultaneously by several teams.

When we moved to the preliminary testing stage, different problems began to appear. Although they were minor, we had to frequently change the documentation — four different teams, every day, almost simultaneously, with discussions. All these changes went through one engineer — the architect. The project design file was huge, and as a result, the architect was overwhelmed with routine work involving a lot of copying and editing. He made a lot of mistakes, everything had to be rechecked and resent. In general, our work was close to chaos.

So, this approach, the approach of working on an MS Word document, worked with great difficulty and created problems.

Git, Markdown

Faced with the problem described in the example above, I began to research this issue.

I noticed that it was becoming more and more popular to use Markdown in conjunction with Git when creating documents.

Git is a development tool. But why not use it for the documentation process? In this case, the issue of multi-user work becomes resolved. But to take full advantage of the power of Git, we need a text-based document format. We need to find another tool, not MS Word. And Markdown would be great for this.

Markdown is a simple markup language. It is used to create beautifully designed texts in regular TXT files. If we create our documents in Markdown, then using Git will look quite natural.

And that would be fine if not for our second condition: “as a result, you want to have a document in a certain format, having corporate style attributes, and created according to a certain template” (and we agreed at the beginning that it would be MS Word). So, if we decide to use Markdown, we need to somehow convert this file to the required .docx format.

There are programs for converting between different formats, for example, Pandoc. Using this program, you can convert a Markdown file to a .docx format. But still, you need to understand that, firstly, not everything that Markdown has will be converted to MS Word and, secondly, MS Word is a whole country compared to the small town of Markdown. There is a huge amount of things that Word has and Markdown does not. You cannot just take certain Pandoc keys and convert your Markdown format into the desired form of MS Word. So, usually, after conversion, you have to “refine” the resulting .docx document manually, which may also be time-consuming and lead to errors.

If we could write a script that automatically “completed” what Pandoc couldn’t handle, that would be the perfect solution.

Since MS Word and Markdown essentially differ, I think it is impossible to solve this problem in general. But is it possible to do it concerning specific situations, specific requirements? My experience has shown that yes, it is possible, and most likely possible in many or maybe even most situations.

Solving a particular problem

So, in my case, after files were converted in Pandoc, I had to additionally process these files manually, i.e.

Add Word fields with the automatic numbering of captions for figures and tables
Change table styles

I could not find how to do this using any standard (Pandoc) or known means. So, I applied a python script with the pywin32 package. As a result, I got full automation. I could convert my Markdown file to the desired MS Word form with just one command.

The pywin32 lets you get almost complete control over MS Word documents, which allows you to change them and bring them to the form that your corporate standard requires. Of course, the same goals could be achieved using other tools, for example, VBA macros, but it was more convenient for me to use python.

A short formula for this approach:

Markdown + Git - (something) → MS Word

It doesn’t matter what “something” is. In my case, that was Pandoc and python with pywin32. You may have different preferences, but the important thing is that it is possible. And that is the main message of this article.

To sum up, the idea is that this approach allows you to work only with Markdown files and use Git for collaboration and version control. If necessary (for example, to provide documentation to the client), you automatically create a file of the desired format (for example, MS Word).

Process

I think for many of you the formula given above is sufficient to understand how the process of working with documentation can now be organized. But still, I usually focus on network engineers. So, I’ll show you in general terms how the work process might look like and how it differs from editing MS Word files.

To be specific, let’s choose GitHub as the platform for working with Git. Then you must create a repository and add the Markdown file or files you plan to work with to the master branch.

Suppose four people are working on documentation, and you are one of them. Then, four additional branches are created, for example, with these people’s names. Each person works locally, in his own branch, and makes changes using all the necessary git commands.

After completing a separate piece of work, you create a pull request, thus initiating a discussion of your changes. Perhaps during the discussion, it turns out that you need to add or change something else. In this case, you make the necessary changes and create an additional pull request. Eventually, your changes are committed and merge into the master branch (or rejected).

Of course, this is a rather general description. I suggest contacting your developers or finding experienced people to create a detailed process. But I would like to point out that Git has a pretty low entry threshold. This doesn’t mean that the protocol is simple, but you can start simple. If you don’t know anything at all, I think after spending a few hours or maybe days learning and installing, you can start using it.

What’s the use of this approach compared to, for example, the process described in the example above?

The processes are quite similar, you just replace:

Copy a file → create a branch
Copy text to a destination file → merge
Copy the latest changes to yourself → git pull/fetch
Chat discussion → pull requests
Track mode → git diff
Latest approved version → master branch
Backup (copy to a remote server) → git push

Thus, you automate everything that you have to do manually.

At a higher level, it allows you to:

Create a clear, simple, and controllable document change process
Since you create the final document (in our case, MS Word) automatically, this reduces the risk of errors associated with formatting

In view of the above, I think it is obvious that even if you are the only one who works with documentation, using Git can make your work much easier.

How do I start a new process?

At the beginning of the article, I’ve written that tomorrow you can start working in a new way. So, how to take your work in a new direction?

Here is the sequence of steps you will most likely need to follow:

If your document is too large, break it into parts
Convert each part to Markdown (using Pandoc, for example)
Install one of the Markdown editors (I use Typora)
Most likely you will need to correct the created Markdown-formatted documents
Start following the process outlined in the previous chapter
Start modifying the conversion script for your task (or create something of your own)

You don’t have to wait until you create and fine-tune the Markdown conversion engine → the required document type. The fact is that even if you cannot quickly automate the process of converting your Markdown files, you can still use Pandoc to convert them to some form, and then manually bring your files to the form you need. Usually, you don’t need to do this too often but only at the end of certain stages. Although this manual work is inconvenient, it is still, in my opinion, quite acceptable at the debugging stage and won’t greatly slow down the process.

Everything else (Markdown, Git, Pandoc, Typora) is ready-made and doesn’t take much effort or time to get started.