Use GIT when documenting
Sometimes not only the documentation itself, but 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 benefits. But even if this topic is not central to your work and is on the periphery, the correct process can still improve the quality of the document and save you time.
The approach outlined here, with an example of a specific implementation , has a low entry threshold. Technically, tomorrow you can start working in a new way.
You need to create a document or set of documents. Perhaps this is project documentation or logging of your network, or something simpler, for example, you should describe the processes in the company or in your department. In general, we are talking about any document or set of documents with text, pictures, tablets ... Let's complicate the task by
10 years ago, the approach would be unambiguous: we would create an MS Word document or documents and somehow organize the work on the change.
')
And this approach is still in force. It is also used by major integrators when creating project documentation. But it is intuitively clear that if you are really intense, with many revisions and discussions, you are working on a document for a long time, this approach is not very convenient.
Faced with the problem described in the example above, I began to investigate this question.
I saw that using Markdown with Git to create documents was becoming increasingly popular.
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 Git's capabilities, we need a text-based document format, we need to find another tool, not 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 ordinary TXT format files. If we create our documents in Markdown, a bunch of Markdown - Git looks natural.
And everything would be fine, and in this place it would be possible to put an end, if not our second condition: “at the exit, we need a document in a certain format, with the attributes of corporate style created according to a certain pattern” (and we agreed at the beginning that certainty it will be MS Word). That is, if we decided to use Markdown, then we need to somehow convert this file to the required type .docx.
There are conversion programs between different formats, for example, Pandoc .
You can convert Markdown file to .docx format with this program.
But still, we must understand that, firstly, not everything that exists in Markdown will be converted into MS Word and, secondly, MS Word is a whole country compared to the slim, but still town, Markdown. There is a huge amount of everything that is in Word and is not in any way in Markdown. You can’t just use your Pandoc keys to convert your Markdown format to the desired MS Word. So usually, after the conversion, you have to “modify” 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” something that Pandoc could not cope with - that would be the perfect solution.
I think it is impossible to solve this problem due to the non-identity of the MS Word and Markdown functional, but can this 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.
So, in my case, after converting a file using Pandoc, I had to manually do additional file processing, namely
I have not found how to do this with standard (Pandoc) or known means. So I used the python script with the pywin32 package. As a result, I got full automation. Now I can convert my Markdown file into the required form of MS Word document with one command.
See details here .
In general, with pywin32 we get almost complete control over the MS Word document, which allows you to change it, and lead to the form that your corporate standard requires. Of course, these same goals could be achieved with the use of other tools, such as VBA macros, but it was more convenient for me to use python.
Brief formula of this approach:
Not so much what “something” is. In my case, it was Pandoc and python with pywin32. You may have other preferences, but what is important is that this is possible. And this is the main message of this article.
In summary, the idea is that with this approach you only work with the Markdown file and use Git to organize collaboration and version control, and only when necessary (for example, to provide documentation to the client) automatically create a file of the desired format (for example, MS Word ).
I think for many 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 in general terms how the work process can look now and how it differs from the approach with editing MS Word files.
For definiteness, choose GitHub as the platform for working with Git. Then you should create a repository and place the Markdown file or files you plan to work with in the master branch.
We will look at a simple process based on github flow. Its description can be found both on the Internet and in the habr .
Suppose there are four people working on the documentation and you are one of them. Then four additional branches are created (branch), for example, with the names of these people. Each works locally, in its branch and makes changes with all the necessary git commands .
After completing some finished piece of work, you form a pull request, thus initiating a discussion of your changes. Perhaps during the discussion, it turns out that you have to add or change something else. In this case, you make the necessary changes and create an additional pull request. In the end, your changes are accepted and merged (merge) with the master branch (or discarded).
Of course, this is quite a general description. I propose to create a detailed process to contact your developers or find knowledgeable people. But I want to note that the threshold for entering Git is quite low. This does not mean that the protocol is simple, but you can start with a simple one. If you do not know anything at all, I think that after spending a few hours or maybe days studying and installing, you can start using it.
What is the use of this approach compared to, for example, the process described in the example above?
In fact, the processes are quite similar, you just replaced
copying a file -> creating a branch (branch)
copying text to the final file-> merge
copying recent changes to yourself -> git pull / fetch
discussion in correspondence -> 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 to
All this improves the quality of documentation and reduces the time to create it. And another small bonus - you will learn Git, which will help you in automating your network :)
At the beginning of the article I wrote that tomorrow you can start working in a new way. How to translate your work in a new direction?
Here is a sequence of steps that you will most likely have to complete:
You don’t have to wait until you create and perfectly debug the Markdwon conversion mechanism -> the type of document required at the output. The fact is that even if you cannot quickly fully automate the process of converting your Markdown files, you can still do it in any form using 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, but still, in my opinion, is quite acceptable at the debugging stage and should not “slow down” the process.
Everything else (Markdown, Git, Pandoc, Typora) is ready and does not require much effort or time to start working with them.
The approach outlined here, with 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 document or set of documents. Perhaps this is project documentation or logging of your network, or something simpler, for example, you should describe the processes in the company or in your department. In general, we are talking about any document or set of documents with text, pictures, tablets ... Let's complicate the task by
- This work involves joint work, the efforts of a group or several groups of employees.
- on exit, 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 be unambiguous: we would create an MS Word document or documents and somehow organize the work on the change.
')
And this approach is still in force. It is also used by major integrators when creating project documentation. But it is intuitively clear that if you are really intense, with many revisions and discussions, you are working on a document for a long time, this approach is not very convenient.
Example
I quite acutely felt this problem, working in one large integrator. The process of changing project documentation was as follows:
- the engineer downloads the latest version of MS Word (.docx) document
- changes name
- makes changes to the track mod
- sends a document with edits to the architect
- also sends a list of all corrections with comments
- the architect analyzes the changes
- if everything is good, then copies these changes to the file with the latest version, changes the version, puts it on a shared resource
- if there are comments, discussion is initiated (email or rallies)
- consensus is reached
- further points 3 - 9
While the work was not intensive, 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 everything becomes bad as soon as changes are made frequently and at the same time by several teams.
So, when we went to the preliminary testing stage, different problems began to appear and, although small things, but it was necessary to change the documentation often - four different teams, daily, almost simultaneously, with discussions. All these changes passed through the same 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 recheck everything, resubmit, and in general it was close to chaos.
In this case, this approach, the approach to work on the MS Word document, worked with a large creak and created problems.
Git markdown
Faced with the problem described in the example above, I began to investigate this question.
I saw that using Markdown with Git to create documents was becoming increasingly popular.
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 Git's capabilities, we need a text-based document format, we need to find another tool, not 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 ordinary TXT format files. If we create our documents in Markdown, a bunch of Markdown - Git looks natural.
And everything would be fine, and in this place it would be possible to put an end, if not our second condition: “at the exit, we need a document in a certain format, with the attributes of corporate style created according to a certain pattern” (and we agreed at the beginning that certainty it will be MS Word). That is, if we decided to use Markdown, then we need to somehow convert this file to the required type .docx.
There are conversion programs between different formats, for example, Pandoc .
You can convert Markdown file to .docx format with this program.
But still, we must understand that, firstly, not everything that exists in Markdown will be converted into MS Word and, secondly, MS Word is a whole country compared to the slim, but still town, Markdown. There is a huge amount of everything that is in Word and is not in any way in Markdown. You can’t just use your Pandoc keys to convert your Markdown format to the desired MS Word. So usually, after the conversion, you have to “modify” 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” something that Pandoc could not cope with - that would be the perfect solution.
I think it is impossible to solve this problem due to the non-identity of the MS Word and Markdown functional, but can this 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 a file using Pandoc, I had to manually do additional file processing, namely
- Add fields with automatic numbering of captions for tables and pictures in Word
- change style for tables
I have not found how to do this with standard (Pandoc) or known means. So I used the python script with the pywin32 package. As a result, I got full automation. Now I can convert my Markdown file into the required form of MS Word document with one command.
See details here .
Comment
In this example, I, of course, transform some abstract Markdown file, but exactly the same approach was applied to the “combat” document, and at the output I received 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 you to change it, and lead to the form that your corporate standard requires. Of course, these same goals could be achieved with the use of other tools, such as VBA macros, but it was more convenient for me to use python.
Brief formula of this approach:
Markdown + Git -- () --> MS Word Not so much what “something” is. In my case, it was Pandoc and python with pywin32. You may have other preferences, but what is important is that this is possible. And this is the main message of this article.
In summary, the idea is that with this approach you only work with the Markdown file and use Git to organize collaboration and version control, and only when necessary (for example, to provide documentation to the client) automatically create a file of the desired format (for example, MS Word ).
Process
I think for many 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 in general terms how the work process can look now and how it differs from the approach with editing MS Word files.
For definiteness, choose GitHub as the platform for working with Git. Then you should create a repository and place the Markdown file or files you plan to work with in the master branch.
We will look at a simple process based on github flow. Its description can be found both on the Internet and in the habr .
Suppose there are four people working on the documentation and you are one of them. Then four additional branches are created (branch), for example, with the names of these people. Each works locally, in its branch and makes changes with all the necessary git commands .
After completing some finished piece of work, you form a pull request, thus initiating a discussion of your changes. Perhaps during the discussion, it turns out that you have to add or change something else. In this case, you make the necessary changes and create an additional pull request. In the end, your changes are accepted and merged (merge) with the master branch (or discarded).
Of course, this is quite a general description. I propose to create a detailed process to contact your developers or find knowledgeable people. But I want to note that the threshold for entering Git is quite low. This does not mean that the protocol is simple, but you can start with a simple one. If you do not know anything at all, I think that after spending a few hours or maybe days studying and installing, you can start using it.
What is the use of this approach compared to, for example, the process described in the example above?
In fact, the processes are quite similar, you just replaced
copying a file -> creating a branch (branch)
copying text to the final file-> merge
copying recent changes to yourself -> git pull / fetch
discussion in correspondence -> 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 to
- create a clear, simple and controllable documentation change process
- because the final document (in our example, MS Word) you create automatically, it reduces the likelihood of errors related to formatting
Comment
In view of the above, I think it is obvious that, even if you are working on the documentation alone, using Git can greatly facilitate your work.
All this improves the quality of documentation and reduces the time to create it. And another small bonus - you will learn Git, which will help you in automating your network :)
How to move to a new process?
At the beginning of the article I wrote that tomorrow you can start working in a new way. How to translate your work in a new direction?
Here is a sequence of steps that you will most likely have to complete:
- if your document is very large, break it apart
- convert each part to Markdown (using Pandoc, for example)
- install one of Markdown editors (I use Typora )
- most likely you will have to correct the formatting of documents created by Markdown
- start using 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 create and perfectly debug the Markdwon conversion mechanism -> the type of document required at the output. The fact is that even if you cannot quickly fully automate the process of converting your Markdown files, you can still do it in any form using 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, but still, in my opinion, is quite acceptable at the debugging stage and should not “slow down” the process.
Everything else (Markdown, Git, Pandoc, Typora) is ready and does not require much effort or time to start working with them.
Source: https://habr.com/ru/post/456410/
All Articles