Use GIT for documentation

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

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

Formulation of the problem

You need to create a certain document or set of documents. Maybe it's the design documentation or the logging of your network, or something simpler, like you need to describe the processes in a company or in your department. In general, we are talking about any document or set of documents with text, pictures, signs ... Let's complicate the task by the fact that

1. this work involves joint work, the efforts of a group or several groups of employees
2. at the output, you want to have a document in a specific format, with corporate style attributes, created according to a specific template. For definiteness, we will assume that this is MS Word (.docx)

10 years ago, the approach would have been unequivocal: we would have created an MS Word document or documents and somehow organized the change work.

And this approach is still valid. It is also used by large integrators when creating project documentation. But it is intuitively clear that if you are really intensive, with many edits and discussions, for a long time working on a document, this approach is not very convenient.

Example

I felt this problem quite acutely while working in one large integrator. The process of changing the project documentation was as follows:

1. engineer downloads the latest MS Word (.docx) document
2. changes name
3. makes changes to the track mode
4. sends the document with revisions to the architect
5. also sends a list of all fixes with comments
6. architect analyzes changes
7. if all is well, then copies these changes to a file with the latest version, changes the version, puts it on the share
8. if there are comments, then a discussion is initiated (email or rallies)
9. consensus is reached
10. further points 3 - 9

While the work was not intensive, then it somehow, but still worked. But at some point, this process became the bottleneck of the whole project and led to problems. The fact is that things get bad as soon as changes are made frequently and simultaneously by several teams.

So, when we moved to the preliminary testing stage, various problems began to appear and, although in small things, it was necessary to change the documentation frequently - four different teams, daily, almost simultaneously, with discussions. All these changes went through one engineer-architect. The project design file was huge, and as a result, the architect was overwhelmed with routine work associated with a lot of copying, editing, made many mistakes, had to double-check everything, resend, and in general it was close to chaos.

In this case, this approach, the approach of working on a MS Word document, worked very creakingly and created problems.

Git, Markdown

Faced with the problem described in the example above, I began to investigate this issue.
I have seen that the use of Markdown with Go 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 in order to take full advantage of the power of Git, we need a text-based document format, we need to find a tool other than MS Word, and Markdown is great for this purpose.

Markdown is a simple text markup language. It is designed to create beautifully designed texts in regular TXT files. If we create our documents in Markdown, then the Markdown - Git bundle looks natural.

And everything would be fine, and at this point it would be possible to put an end to it, if not for our second condition: “at the output we need a document in a certain format, with corporate style attributes, created according to a certain template” (and we agreed at the beginning that for Certainly it will be MS Word). That is, if we decide to use Markdown, then we need to somehow convert this file into .docx of the required form.

There are programs for converting between different formats, for example, pandoc.
You can convert Markdown file to .docx format with this program.
But still, you need to understand that, firstly, not everything that is in Markdown will be converted to MS Word and, secondly, MS Word is a whole country compared to the slender, but still town, Markdown. There is a huge amount of everything that is in Word and in any form is not in Markdown. You can’t just take it and with certain Pandoc keys convert your Markdown format to the desired MS Word look. So usually, after conversion, you have to “finish” the resulting .docx document manually, which again can be time-consuming and lead to errors.

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

Due to the non-identity of the functionality of MS Word and Markdown, in general terms, it is impossible to solve this problem, but can it be done in relation to specific situations, specific requirements? My experience has shown that yes, it is possible and most likely it is possible for many, or maybe even most situations.

Solving a particular problem

So, in my case, after converting the file using Pandoc, I had to manually do additional file processing, namely

• add fields to Word with automatic numbering of headings (caption) of tables and pictures
• change style for tables

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

see details here.

Comment

In this example, of course, I am converting some abstract Markdown file, but exactly the same approach was applied to the “combat” document, and the output was almost exactly the same MS Word document that we previously received by manual formatting.

In general, with pywin32 we get almost complete control over the MS Word document, which allows us to change it and bring it to the form that your corporate standard requires. Of course, the same goals could be achieved using other tools, such as VBA macros, but it was more convenient for me to use python.

The short formula for this approach is:

Markdown + Git -- (нечто) --> MS Word

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

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

Process

I think for many, the above formula 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 will show in general terms how the work process can now look like, and how it differs from the approach with editing MS Word files.

For definiteness, we will choose GitHub as the platform for working with Git. Then you should create a repository and put the Markdown file or files you plan to work with on the master branch.

We'll walk through a simple process based on the "github flow". Its description can be found both on the Internet and on habre.

Suppose there are four people working on the documentation and you are one of them. Then four additional branches (branch) are created, for example, with the names of these people. Everyone works locally, on their own branch, and makes changes with all the necessary git commands.

After completing some completed piece of work, you form a pull request, thus initiating a discussion of your changes. Perhaps, in the process of discussion, it turns out that you should add or change something else. In this case, you make the necessary changes and create an additional pull request. Eventually, your changes are accepted and merged into the master branch (or discarded).

Of course, this is a fairly general description. I suggest that you contact your developers or find knowledgeable people to create a detailed process. But I want to note that the threshold for entering Git is quite low. This is not to say 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 to learn and install, you can start using it.

What is the benefit of this approach compared to, for example, the process described in the example above?

In fact, the processes are quite similar, you just replaced

copy file -> create branch (branch)
copy text to destination file-> merge (merge)
copy the latest changes to yourself -> git pull/fetch
chat discussion -> pull requests
track mode -> git diff
latest approved version -> master branch
backup (copying to a remote server) -> git push
...

Thus, you have automated everything that you already had to do, but manually.

At a higher level, this allows you

• create a clear, simple and controlled process for documentation changes
• because the final document (in our example, MS Word) you create automatically, this reduces the likelihood of formatting errors

Comment

By virtue of the above, I think it is obvious that even if you work on the documentation alone, then using Git can greatly facilitate your work.

All this improves the quality of documentation and reduces the time for its creation. And a little bonus - you will learn Git, which will help you with automating your network 🙂

How to switch to a new process?

At the beginning of the article, I wrote that tomorrow you can start working in a new way. 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 very large, split it into parts
• convert each part to Markdown (with Pandoc for example)
• install one of the Markdown editors (I use typora)
• most likely you will have to correct the formatting of the generated Markdown documents
• start applying the process described in the previous chapter
• in parallel, start modifying the conversion script for your task (or create something of your own)

You don't have to wait until you've built and fine-tuned the Markdwon conversion engine -> the desired output document type. The thing is, even if you can't quickly fully automate the process of converting your Markdown files, you can still do it in some form with Pandoc and then bring it to the final form manually. Usually you do not need to do this often, but only at the end of certain stages, and this manual work, although inconvenient, is still, in my opinion, quite acceptable at the debugging stage and should not “slow down” the process much.

Everything else (Markdown, Git, Pandoc, Typora) is out of the box and takes little effort or time to get started.

Source: habr.com