Använd GIT vid dokumentation

Ibland är det inte bara själva dokumentationen som är kritisk, utan även processen att arbeta med den. Till exempel, i projekten utgör en stor del av arbetet själva förberedelsen av dokumentationen och en felaktig process kan leda till misstag och till och med förlust av information, vilket i sin tur kan leda till förlust av tid och vinster. Men även om detta tema inte är centralt i ditt arbete och ligger på periferin, kan rätt process fortfarande förbättra kvaliteten på dokumentet och spara tid.

Den här metoden, med ett exempel på specifik implementering, har en låg tröskel för inträde. Tekniskt sett kan du börja arbeta på ett nytt sätt redan imorgon.

Uppgiftsställande

Du behöver skapa något dokument eller en uppsättning dokument. Kanske handlar det om projektdokumentation eller loggning av ditt nätverk, eller något enklare, som att du måste beskriva processerna i företaget eller avdelningen. Det handlar om vilket dokument eller uppsättning dokument som helst med text, bilder, tabeller… Vi komplicerar uppgiften genom att

1. detta arbete förutsätter samarbete, insatser från en grupp eller flera grupper av medarbetare
2. och slutresultatet är att du vill ha ett dokument i ett visst format, med egenskaper som följer företagets stil, skapat enligt en viss mall. För tydlighetens skull kommer vi att anta att det handlar om MS Word (.docx)

För 10 år sedan hade tillvägagångssättet varit entydigt: vi skulle ha skapat ett eller flera MS Word-dokument och organiserat arbetet med att göra ändringar på något sätt.

Och det tillvägagångssättet gäller fortfarande. Det används även av stora integratörer vid skapandet av projektdokumentation. Men det är intuitivt klart att om du arbetar intensivt med många ändringar och diskussioner under en längre tid, är detta tillvägagångssätt inte särskilt bekvämt.

Exempel

Jag kände av detta problem ganska tydligt när jag arbetade på en stor integrator. Processen för att ändra projektdokumentationen såg ut som följande:

1. ingenjören laddar ner den senaste versionen av MS Word-dokumentet (.docx)
2. ändrar namnet
3. gör ändringar i spårningsläge
4. skickar dokumentet med ändringarna till arkitekten
5. skickar också en lista med alla korrigeringar och kommentarer
6. arkitekten analyserar ändringarna
7. om allt går bra, kopierar den dataändringarna till filen med den senaste versionen, ändrar versionen och lägger ut den på en gemensam resurs
8. om det finns invändningar initieras en diskussion (e-post eller möten)
9. konsensus uppnås
10. därefter punkterna 3–9

När arbetet inte var intensivt funkade det i alla fall, men vid en viss punkt blev denna process det svaga länken i hela projektet och ledde till problem. Det handlar om att allt går snett så snart ändringar görs ofta och samtidigt av flera team.

Så när vi gick in i fasen av preliminär testning började olika problem dyka upp, och även om de var små behövde dokumentationen ändras ofta — fyra olika team, dagligen, praktiskt taget samtidigt, med diskussioner. Alla dessa ändringar gick genom en ingenjör — arkitekten. Projektets designfil var enorm, och som följd av detta blev arkitekten överhopad med rutinarbete, inklusive mycket kopiering och redigering, gjorde många misstag, behövde alltid dubbelkolla, åter skicka, och det var nära kaos.

I det här fallet fungerade denna metod, metoden för arbete med MS Word-dokument, med stor ansträngning och skapade problem.

Git, Markdown

Kände jag mig tvungen att utforska problemet som beskrevs i exemplet ovan.
Jag såg att det blir allt mer populärt att använda Markdown tillsammans med Git vid skapande av dokument.

Git är ett verktyg för utveckling. Men varför inte använda det för dokumentationsprocessen? I det här fallet blir frågan om flervalsarbete löst. Men för att fullt ut dra nytta av Git:s möjligheter behöver vi ett textformat för dokumentet, vi måste hitta ett annat verktyg, inte MS Word, och för dessa ändamål passar Markdown utmärkt.

Markdown är ett enkelt textmarkeringsspråk. Det är avsett för att skapa vackert formaterade texter i vanliga TXT-filformat. Om vi skapar våra dokument i Markdown, verkar kopplingen Markdown – Git naturlig.

Och allt skulle vara bra, och på denna punkt skulle man kunna sätta punkt, om det inte vore för vårt andra villkor: "vi behöver ett dokument i ett visst format, med attribut av företagets stil, skapat enligt en viss mall" (och vi kom överens om att det i detta fall skulle vara MS Word). Det vill säga, om vi har beslutat att använda Markdown, så måste vi på något sätt omvandla denna fil till .docx i önskat format.

Det finns program för konvertering mellan olika format, till exempel, Pandoc.
Du kan konvertera en Markdown-fil till .docx-format med detta program.
Men ändå, man måste förstå att, för det första, inte allt som finns i Markdown kommer att konverteras till MS Word och, för det andra, MS Word är ett helt annat universum jämfört med det smidiga, men ändå lilla, Markdown. Det finns en enorm mängd funktioner i Word som inte finns i något format av Markdown. Man kan inte bara ta och använda vissa nycklar för Pandoc för att konvertera din Markdown-format till det önskade MS Word-utseendet. Så vanligtvis, efter konverteringen, måste man "arbeta om" den erhållna .docx-dokumentet manuellt, vilket också kan vara tidskrävande och leda till fel.

Om vi skulle kunna skriva ett skript som automatiskt "slutförde" det som Pandoc inte klarade skulle det vara en idealisk lösning.

På grund av olikheterna i funktionaliteten mellan MS Word och Markdown i allmänhet är det, tror jag, omöjligt att lösa denna uppgift, men kan detta göras i specifika situationer, med specifika krav? Min erfarenhet har visat att ja, det går, och troligtvis är det möjligt för många, eller kanske till och med de flesta situationer.

Lösningen på ett specifikt problem

Så, i mitt fall, efter att ha konverterat filen med hjälp av Pandoc, var jag tvungen att göra ytterligare bearbetning av filer manuellt, nämligen

• att lägga till fält med automatisk numrering av rubriker (caption) för tabeller och bilder i Word
• att ändra stil för tabeller

Jag kunde inte hitta hur man gör detta med standard (Pandoc) eller kända medel. Därför använde jag ett Python-skript med pywin32 paketet. Resultatet blev full automatisering. Nu kan jag konvertera min Markdown-fil till den önskade formen av MS Word-dokumentet med ett enda kommando.

Se detaljer här.

Anmärkning

I det här exemplet kommer jag naturligtvis att konvertera en viss abstrakt Markdown-fil, men exakt samma metod har använts på ett "battle-ready" dokument, och resultatet blev praktiskt taget samma MS Word-dokument som vi tidigare fått genom manuell formatering.

Generellt sett får vi med pywin32 nästan full kontroll över MS Word-dokumentet, vilket gör att vi kan ändra det och anpassa det till ert företags standard. Självklart kan dessa mål också uppnås med andra verktyg, som VBA-makron, men det var enklare för mig att använda python.

Den korta formeln för denna metod är:

Markdown + Git -- (något) --> MS Word

Det spelar inte så stor roll vad "något" är. I mitt fall var det Pandoc och python med pywin32. Kanske har du andra preferenser, men det viktiga är att det är möjligt. Och det är kärnan i denna artikel.

Sammanfattningsvis är idén att med denna metod arbetar du endast med Markdown-filen och använder Git för att organisera samarbete och versionskontroll, och endast vid behov (till exempel för att ge dokumentation till en klient) automatiskt skapa en fil i rätt format (till exempel MS Word).

Process

Jag tror att för många är formeln ovan tillräcklig för att förstå hur dokumentationsprocessen nu kan organiseras. Men jag brukar ofta rikta mig mot nätverksingenjörer, så jag ska i grova drag visa hur arbetsprocessen nu kan se ut, och hur det skiljer sig från tillvägagångssättet med att redigera MS Word-filer.

För tydlighetens skull, som plattform för arbete med Git väljer vi GitHub. Då bör du skapa ett repository och placera Markdown-filen eller filerna som du planerar att arbeta med i master-grenen.

Vi kommer att titta på en enkel process baserad på "github flow". En beskrivning av den kan hittas både på nätet och på Habré.

Anta att fyra personer arbetar med dokumentationen och du är en av dem. Då skapas fyra ytterligare grenar (branches), till exempel med namnen på dessa personer. Var och en arbetar lokalt, i sin egen gren, och gör ändringar med alla nödvändiga git-kommandon.

När du har slutfört en viss del av arbetet skapar du en pull request, vilket initierar en diskussion om dina ändringar. Under diskussionen kan det visa sig att du behöver lägga till eller ändra något mer. I så fall gör du de nödvändiga ändringarna och skapar en viss pull request. Slutligen godkänns dina ändringar och slås ihop (merge) med master-grenen (eller avvisas).

Självklart är detta en ganska allmän beskrivning. Jag föreslår att ni kontaktar era utvecklare eller finner personer med kunskap för att skapa en mer detaljerad process. Men jag vill påpeka att tröskeln för att börja använda Git är ganska låg. Detta innebär inte att protokollet är enkelt, men du kan börja med något grundläggande. Om du inte alls vet något, tror jag att du kan sätta av några timmar eller kanske dagar för att lära dig och installera det så att du kan börja använda det.

Vad är då nyttan med detta tillvägagångssätt jämfört med processen som beskrivs i exemplet ovan?

I själva verket är processerna ganska lika, du har bara bytt ut

filkopiering -> skapa en gren (branch)
klistra in text i den slutliga filen -> sammanslagning (merge)
kopiera de senaste ändringarna till dig -> git pull/fetch
diskussion i korrespondensen -> pull requests
spårningsläge -> git diff
den senaste godkända versionen -> master-gren
backup (kopiera till en fjärrserver) -> git push
…

På så sätt har du automatiserat allt som du annars skulle behöva göra, men manuellt.

På en högre nivå gör detta att du

• kan skapa en tydlig, enkel och kontrollerad process för ändringar av dokumentation
• eftersom det slutliga dokumentet (i vårt exempel MS Word) genereras automatiskt, minskar det risken för fel relaterade till formatering

Anmärkning

Med detta sagt tror jag att det är uppenbart att även om du arbetar ensam med dokumentationen, kan användning av Git avsevärt förenkla ditt arbete.

Allt detta förbättrar kvaliteten på dokumentationen och minskar tiden för dess skapande. Och en liten bonus — du kommer att lära dig Git, vilket kommer att hjälpa dig i automatiseringen av ditt nätverk 🙂

Hur går man över till den nya processen?

I början av artikeln skrev jag att du redan imorgon kan börja arbeta på ett nytt sätt. Hur går du över din arbetsmetod till ett nytt spår?

Här är en sekvens av steg som du troligen måste följa:

• om ditt dokument är väldigt stort, dela upp det i delar
• konvertera varje del till Markdown (med Pandoc, till exempel)
• installera en av Markdown-redigerarna (jag använder Typora)
• du kommer förmodligen behöva justera formateringen av de skapade Markdown-dokumenten
• börja tillämpa processen som beskrivs i föregående kapitel
• samtidigt kan du börja anpassa konverteringsscriptet för ditt syfte (eller skapa något eget)

Du behöver inte vänta tills du har skapat och debuggar omvandlingsmekanismen Markdown -> önskat dokumentutseende perfekt. Faktum är att även om du inte lyckas automatisera omvandlingen av dina Markdown-filer helt och hållet snabbt kan du fortfarande göra det på något sätt med Pandoc och sedan få det till det slutgiltiga utseendet manuellt. Vanligtvis behöver du inte göra detta ofta, utan bara i slutet av vissa steg, och detta manuella arbete, även om det är obekvämt, är enligt min mening helt acceptabelt under debug-fasen och bör inte kraftigt „bromsa“ processen.

Allt annat (Markdown, Git, Pandoc, Typora) är redan klart och kräver inte särskilda ansträngningar eller tid för att börja arbeta med dem.

Källa: habr.com