Brug GIT i dokumentationen

Nogle gange kan ikke kun dokumentationen selv, men også processen med at arbejde med den være kritisk. For eksempel, i tilfælde af projekter er en stor del af arbejdet forbundet med forberedelsen af dokumentationen, og en forkert proces kan føre til fejl og endda tab af information, og dermed også tab af tid og gevinst. Men selv hvis dette emne ikke er centralt for dit arbejde og ligger på periferien, kan den rigtige proces stadig forbedre kvaliteten af dokumentet og spare dig tid.

Den præsenterede tilgang, med eksemplet på en konkret implementering, har en lav indgangsbarriere. Teknisk set kan du allerede i morgen begynde at arbejde anderledes.

Problemformulering

Du skal oprette et eller andet dokument eller en række dokumenter. Det kan være projektdokumentation eller protokollering af dit netværk, eller noget mere simpelt, som at du skal beskrive processer i virksomheden eller i din afdeling. Kort sagt handler det om ethvert dokument eller sæt af dokumenter med tekst, billeder, tabeller... Lad os gøre opgaven sværere, da

1. dette arbejde forudsætter fælles indsats, teamarbejde eller fra flere grupper af medarbejdere
2. og du ønsker at have et dokument i et bestemt format, med corporate style attributter, lavet efter en specifik skabelon. For tydelighedens skyld antager vi, at det er MS Word (.docx)

For 10 år siden ville tilgangen have været entydig: vi ville have oprettet MS Word-dokument eller dokumenter og på en eller anden måde organiseret arbejdet med ændringer.

Og denne tilgang er stadig gældende. Den anvendes også af store integratorer til at oprette projektdokumentation. Men det er intuitivt klart, at hvis du virkelig arbejder intensivt, med mange rettelser og diskussioner, over en længere periode på et dokument, er denne tilgang ikke særlig praktisk.

Eksempel

Jeg mærkede skarpt dette problem, mens jeg arbejdede i en stor integrator. Processen for ændringer i projektdokumentationen var som følger:

1. ingeniøren downloader den seneste version af MS Word (.docx) dokumentet
2. ændrer titlen
3. foretager ændringer i track mode
4. sender dokumentet med ændringer til arkitekten
5. sender også en liste over alle rettelser med kommentarer
6. arkitekten analyserer ændringerne
7. hvis alt ser godt ud, kopierer han de ændringer til filen med den seneste version, ændrer versionen, og uploader den til den fælles ressource
8. hvis der er bemærkninger, initieres en diskussion (email eller møder)
9. der opnås enighed
10. herefter punkterne 3 - 9

Indtil arbejdet blev intensivt, fungerede det nogenlunde, men det virkede stadig. Men på et tidspunkt blev denne proces et flaskehals for hele projektet og førte til problemer. Problemet er, at alt bliver dårligt, så snart ændringer foretages ofte og samtidig af flere teams.

Da vi gik ind i fasen for præ-testning, begyndte forskellige problemer at vise sig, og selvom de var små, var det nødvendigt at ændre dokumentationen ofte - fire forskellige teams, dagligt, næsten samtidig, med diskussioner. Alle disse ændringer gik gennem én ingeniør - arkitekten. Filen med designet var kæmpestor, og som følge deraf var arkitekten overbebyrdet med rutinearbejde, der involverede meget kopiering og redigering, lavede mange fejl, det skulle kontrolleres, genfremsendes, og det hele var tæt på kaos.

I dette tilfælde fungerede denne metode, MS Word dokumentarbejdsmetoden, med stor besvær og skabte problemer.

Git, Markdown

Da jeg stødte på problemet beskrevet i det ovenstående eksempel, begyndte jeg at undersøge dette emne.
Jeg så, at det bliver mere og mere populært at bruge Markdown sammen med Git til at oprette dokumenter.

Git er et udviklingsværktøj. Men hvorfor ikke bruge det til dokumentationsprocessen? I så fald bliver spørgsmålet om flerbrugerarbejde løst. Men for at kunne udnytte Gits muligheder fuldt ud har vi brug for et tekstformatdokument, vi skal finde et andet værktøj, ikke MS Word, og til disse formål passer Markdown perfekt.

Markdown er et simpelt tekstmarkup-sprog. Det er designet til at skabe smukt formaterede tekster i almindelige TXT-filer. Hvis vi opretter vores dokumenter i Markdown, ser kombinationen Markdown - Git naturlig ud.

Altogether, this situation could have been resolved if it weren’t for our second condition: 'we need a document in a specific format, with corporate style attributes, created according to a certain template' (and we agreed at the beginning that to be specific, this would be MS Word). In other words, if we decided to use Markdown, we need some way to convert this file to .docx in the required format.

There are conversion programs between various formats, such as Pandoc.
You can convert a Markdown file to .docx format using this program.
However, it is important to understand that, firstly, not everything present in Markdown will be converted to MS Word, and secondly, MS Word is a whole country compared to the well-structured, yet small town of Markdown. There is a huge amount of content available in Word that is absent in Markdown. You cannot simply convert your Markdown format to the desired MS Word format using specific keys in Pandoc. So typically, after conversion, one has to 'refine' the resulting .docx document manually, which can again be time-consuming and lead to errors.

If we could write a script that would automatically 'finish' what Pandoc couldn’t handle—this would be the ideal solution.

Due to the non-equivalence of the functionalities of MS Word and Markdown in general, I believe it is impossible to solve this task; however, can it be done in specific situations with concrete requirements? My experience has shown that yes, it is possible and likely achievable for many, if not most, situations.

Solving a specific issue

Thus, in my case, after converting the file using Pandoc, I had to manually perform additional processing on the files, namely,

• adding fields in Word for automatic numbering of captions for tables and images
• changing the style for tables

I didn’t find a way to do this with standard (Pandoc) or known tools. Therefore, I applied a Python script with pywin32 package. As a result, I achieved full automation. Now I can convert my Markdown file into the required form of an MS Word document with a single command.

See details her.

Bemærkning

I dette eksempel vil jeg naturligvis omforme en eller anden abstrakt Markdown-fil, men nøjagtig samme tilgang er blevet anvendt på et 'operationelt' dokument, og resultatet var stort set det samme MS Word-dokument, som vi tidligere fik ved manuel formatering.

Generelt set giver pywin32 os praktisk taget fuld kontrol over MS Word-dokumentet, hvilket gør det muligt at ændre det og tilpasse det til dit virksomhedsstandard. Selvfølgelig kunne disse mål også opnås med andre værktøjer, som for eksempel VBA-makroer, men jeg fandt det lettere at bruge python.

Den korte formel for denne tilgang er:

Markdown + Git -- (noget) --> MS Word

Det er ikke så vigtigt, hvad 'noget' er. I mit tilfælde var det Pandoc og python med pywin32. Måske har du andre præferencer, men det vigtige er, at det er muligt. Og det er essensen af denne artikel.

Sammenfattende er ideen, at ved at anvende denne tilgang arbejder du kun med Markdown-filen og bruger Git til at organisere samarbejdet og versioneringen, og kun når det er nødvendigt (for eksempel for at give dokumentation til en kunde) opretter du automatisk den nødvendige filtype (for eksempel MS Word).

Proces

Jeg tror, at for mange er formlen anført ovenfor tilstrækkelig til at forstå, hvordan processen med dokumentation nu kan organiseres. Men jeg har sædvanligvis fokus på netværksingeniører, så jeg vil overordnet vise, hvordan arbejdsprocessen nu kan se ud, og hvordan det adskiller sig fra tilgangen med redigering af MS Word-filer.

For tydelighedens skyld vil vi vælge GitHub som platform for arbejdet med Git. Så skal du oprette et repository og placere Markdown-filen eller -filerne, som du planlægger at arbejde med, i master-grenen.

Vi vil gennemgå en simpel proces baseret på 'github flow'. En beskrivelse kan findes både på internettet og på Habr..

Antag, at fire personer arbejder på dokumentationen, og du er en af dem. Så oprettes der fire ekstra grene (branch), for eksempel med navnene på disse personer. Hver person arbejder lokalt i deres gren og foretager ændringer med alle nødvendige git-kommandoer..

Når du har udført en bestemt del af arbejdet, danner du en pull request, som på den måde igangsætter diskussionen om dine ændringer. Det kan være, at der under diskussionen viser sig, at du skal tilføje eller ændre noget andet. I så fald laver du de nødvendige ændringer og opretter en yderligere pull request. Til sidst godkendes dine ændringer og flettes (merge) med master-grenen (eller afvises).

Selvfølgelig er dette en ret generel beskrivelse. Jeg foreslår at tage kontakt til jeres udviklere eller finde personer, der har viden om dette, for at oprette en detaljeret proces. Men jeg vil gerne nævne, at indgangsbarrieren for Git er ret lav. Det betyder ikke, at protokollen er simpel, men du kan begynde med det grundlæggende. Hvis du slet ikke ved noget, tror jeg, at hvis du bruger et par timer eller måske dage på at lære det og installere det, kan du hurtigt komme i gang.

Hvad er fordelene ved denne tilgang sammenlignet med for eksempel den proces, der er beskrevet i ovenstående eksempel?

Faktisk er processerne ret ens, du har blot erstattet

kopiering af fil -> oprettelse af gren (branch)
kopiering af tekst til den endelige fil -> sammenfletning (merge)
kopiering af de seneste ændringer til dig -> git pull/fetch
diskussion i korrespondance -> pull requests
track mode -> git diff
den seneste godkendte version -> master-gren
backup (kopiering til en fjernserver) -> git push
…

På denne måde har du automatiseret alt det, du tidligere måtte gøre manuelt.

På et højere niveau muliggør dette, at du

• opretter en klar, enkel og kontrolleret proces for ændringer i dokumentationen.
• Da det endelige dokument (i vores eksempel MS Word) oprettes automatisk, reducerer det risikoen for fejl relateret til formatering.

Bemærkning

Givet det ovenstående er det klart, at selv hvis du arbejder alene med dokumentationen, kan brugen af Git i høj grad lette dit arbejde.

Alt dette øger kvaliteten af dokumentationen og reducerer tiden til at oprette den. Og endnu en lille bonus - du lærer Git, hvilket vil hjælpe dig med at automatisere dit netværk 🙂.

Hvordan overgår man til den nye proces?

I begyndelsen af artiklen nævnte jeg, at du allerede i morgen kan begynde at arbejde på en ny måde. Hvordan kan du bringe dit arbejde over i et nyt spor?

Her er rækkefølgen af trin, som du sandsynligvis bliver nødt til at udføre:

• hvis dit dokument er meget stort, skal du opdele det i dele.
• konverter hver del til Markdown (f.eks. ved hjælp af Pandoc)
• installer en af Markdown-editorerne (jeg bruger Typora)
• du bliver sandsynligvis nødt til at justere formateringen af de oprettede Markdown-dokumenter
• begynd at anvende den proces, der er beskrevet i det forrige kapitel
• samtidig kan du begynde at tilpasse konverteringsscriptet til din opgave (eller lav noget eget)

Du behøver ikke at vente med at skabe og fejlsøge konverteringsmekanismen Markdown -> det krævede output-dokument. Det er sådan, at selvom du ikke hurtigt kan automatisere proceduren for konvertering af dine Markdown-filer fuldstændigt, kan du stadig gøre det i en eller anden form ved hjælp af Pandoc og derefter nå frem til det endelige udseende manuelt. Normalt behøver du ikke at gøre dette ofte, kun i slutningen af bestemte faser, og dette manuel arbejde, selvom det er besværligt, er efter min mening helt acceptabelt i fejlfindingsstadiet og bør ikke bremse processen betydeligt.

Alt andet (Markdown, Git, Pandoc, Typora) er allerede klar og kræver ikke særlige anstrengelser eller tid for at komme i gang med dem.

Kilde: habr.com