Clever Geek Handbook

We document the process of connecting and generating documents in a future ERP system

image



A few months ago, I completed one of the stages of my professional career as a multi-armed Shiva in a startup on developing a non-destructive testing laboratory management system. I will tell you how I was able to document a part of the development related to connecting and generating documents in sufficient volume for the further quiet use of the created system for two years.



I will try to give the reader useful material as much as possible, and at the same time observe the interests of the project and not divulge the nuances of implementation and internal use.



Given:





A task:





I must say right away that the following document templates were made without any methodology, I was guided solely by the specifics of the project, common sense and a terrible time limit.



Analysis and preparation



I hope that you begin any non-trivial task with the analysis of the material, in my case the material was document templates and an existing project with which integration was needed. But then we are only talking about documents. I needed to determine the frequency of using the same type of data within the same document and between documents. This was necessary to understand whether a system is needed right now or you can quickly do it on the knee first, and then deal with the result. At that time, it was decided that the system is needed, since almost all data, in one volume or another, was repeated inside one document and in the entire package of documents - and this is a sure sign of confusion already on the second or third document when connecting.



The next step is to understand the cleanliness of the markup of documents. Will explain. The fact is that I received already filled out document templates from the methodologist - who, when and how did these documents I did not know, even if I knew this would have given little. The .docx document inside is something like xml for text and some elements may not be visible visually in the open document, but be present in the markup of the document. It is not known how the document generator and various software for viewing the document will react to these markup elements. The main bet was on Microsoft Word, but there are OpenOffice, LibreOffice and all of them can give different results. Therefore, all the templates first went through the style cleaning process - a complete reset of any design and re-design with document styles, somewhere with adjusting the structure of the document. And even after this procedure, we collected problems in the contents of the documents after generation. In the future, I came to the conclusion that if the document is small, it is better to re-sort it from scratch, and not take the template provided by the methodologist into work, this saves time on documents up to 5 pages. Nobody wants to then look for the reason why something went, the process of debugging these cases is extremely tedious for the team. At the same stage, if you have a package of documents, you come to a uniform visual language.



And since we performed a rite of document cleansing, the easter egg in meta-information suggested itself, because people like to share good documents

image

After all the work related to the preparation of documents, I proceeded to marking up documents for automatic generation.



Markup of documents



At this stage, ask the developers for the variable format that supports the document generator selected by your team so that you do not have to redo it later. I had to redo it, but this was due to replacing the generator. The new generator could not work with the variables in the previous format, but the capabilities of the new generator turned out to be more important for us and we decided to replace it.



Check the sufficiency of information in the system, determine how much data is not enough for the document. When is this data supposed to appear on the system? If there is not enough data for the self-sufficiency of the document, it is better to postpone it. What is document self-sufficiency? In my case, there was one document that we completed in 3 stages, but it was self-sufficient immediately for one specific scenario, but did not cover the rest of the scenarios, so we decided to roll out the document for sale leaving empty cells for the user to fill out for uncovered scripts, and subsequently finished off the document with the appearance of the necessary functionality.



Documentation of variables and interface



At the beginning of the note, I wrote that we were strictly limited to a specific event. On top of that, I already had a vacation planned. When I was unavailable, but I urgently needed to add a system variable (not available in the end user interface), the developers added the line with the variable themselves, and then I added the missing conditions. In this regard, the specification of variables does not pretend to be correct and ideal, but it is quite a working document, which subsequently expanded and evolved. The main tab in the document did not structurally change from the start and at the time of my departure of the project.



image



Template “ Specifications for these fields ”, which you can take and use in your work. In the document, I left some of the data for an example. This template may be suitable for interface documentation to control development quality. For example, a product owner knows what minimum result he will get, a developer clearly understands what minimum needs to be done from the task description + specification of these fields, and if something is missing he will tell about this, the testing engineer clearly sees obvious cases. In the end, everything is in the black.



At first, the document will take a significant number of hours, but then it will save you a lot of time, and updating will occasionally take literally minutes.



Content:





Document Connection Documentation



To receive the document by the end user, it is not enough to edit and mark it up; the document still needs to be connected correctly. It is especially important if you have the same template, depending on the conditions, changes its content. For this, I used a separate document.



image



Template " Document Connection ", I hope that it is useful to someone.



Content:





Total



As a result, I filled in 362 lines in both documents. Impressive volume? But in reality, this is 30+ document templates and a total of 40-60 hours of work of one person in two years (1-1.5 weeks) is spent, excluding the editing of the templates themselves and the wording of the connection tasks.



The project successfully passed acceleration in the IIDF and came to the form of its own development team. Thanks to the existing documentation, the new team members did not have to delve into what was done to them regarding the generation of documents. All team members had access to the current status of connected documents at any time.



The main stages in the documentation of the document generation process:





Thanks for getting to the end.


More articles:


All Articles