Bruk GIT ved dokumentasjon

Noen ganger kan ikke bare selve dokumentasjonen, men også prosessen med å arbeide med den, være kritisk. For eksempel, i tilfelle av prosjekter, er en stor del av arbeidet knyttet til forberedelsen av dokumentasjonen, og en feil prosess kan føre til feil og til og med tap av informasjon, og dermed også tap av tid og fortjeneste. Men selv om dette emnet ikke er sentralt i arbeidet ditt og befinner seg på periferien, kan en riktig prosess fortsatt forbedre kvaliteten på dokumentet og spare deg for tid.

Tilnærmingen som er presentert her, med et eksempel på konkret implementering, har lav inngangsbarriere. Teknisk sett kan du allerede i morgen begynne å jobbe på en ny måte.

Definering av oppgaven

Du må lage et dokument eller et sett med dokumenter. Det kan være prosjekt- eller nettverksdokumentasjon, eller noe enklere, for eksempel at du må beskrive prosessene i selskapet eller avdelingen din. Generelt handler det om hvilket som helst dokument eller sett med dokumenter med tekst, bilder, tabeller... La oss komplisere oppgaven med at

1. dette arbeidet forutsetter samarbeid, innsats fra en gruppe eller flere grupper ansatte
2. og på slutten ønsker du å ha et dokument i et bestemt format, med attributter av bedriftsidentitet, laget etter en bestemt mal. For klarhetens skyld, la oss anta at dette er MS Word (.docx)

For 10 år siden ville tilnærmingen vært entydig: vi ville laget MS Word-dokumentet eller -dokumentene og på en eller annen måte organisert arbeidet med endringene.

Og denne tilnærmingen er fortsatt gyldig. Den brukes av blant annet store integratorer når de lager prosjekt- dokumentasjon. Men det er intuitivt forståelig at hvis du virkelig jobber intensivt, med mange endringer og diskusjoner, over en lengre periode med ett dokument, er denne tilnærmingen ikke veldig praktisk.

Eksempel

Jeg opplevde dette problemet ganske sterkt mens jeg jobbet i en stor integrator. Prosessen for å endre prosjekt- dokumentasjonen var som følger:

1. ingeniøren laster ned den siste versjonen av MS Word (.docx)-dokumentet
2. endrer navnet
3. foretar endringer i sporingsmodus
4. sender dokumentet med endringer til arkitekten
5. sender også en liste over alle endringer med kommentarer
6. arkitekten analyserer endringene
7. hvis alt ser bra ut, kopierer han dataene inn i filen med den siste versjonen, endrer versjonen og legger den ut på en felles ressurs
8. hvis det er bemerkninger, vil det bli initiert en diskusjon (e-post eller møter)
9. det oppnås enighet
10. deretter punktene 3 - 9

Så lenge arbeidet ikke har vært intensivt, har det på en eller annen måte fungert. Men på et bestemt tidspunkt ble denne prosessen et flaskehals i hele prosjektet og førte til problemer. Når endringer skjer ofte og samtidig av flere team, blir det vanskelig.

Da vi gikk over til stadiet med forhåndstesting, begynte forskjellige problemer å dukke opp, og selv om det var småting, måtte vi ofte endre dokumentasjonen — fire forskjellige team, daglig, nesten samtidig, med diskusjoner. Alle disse endringene gikk gjennom én ingeniør — arkitekten. Filen med prosjektets design var enorm, som et resultat var arkitekten overbelastet med rutinearbeid som involverte mye kopiering, redigering, gjorde mange feil, måtte sjekkes og sendes på nytt, og det var generelt nær kaos.

I dette tilfellet fungerte denne tilnærmingen, arbeid med MS Word-dokumentet, med stor motgang og skapte problemer.

Git, Markdown

Da jeg stod overfor problemet beskrevet i eksemplet ovenfor, begynte jeg å undersøke dette spørsmålet.
Jeg så at det ble mer og mer populært å bruke Markdown sammen med Git i opprettelsen av dokumenter.

Git er et verktøy for utvikling. Men hvorfor ikke bruke det til dokumentasjonsprosessen? På denne måten blir spørsmålet om flermannsarbeid løst. Men for å fullt utnytte mulighetene med Git trenger vi et tekstformat for dokumentet, og vi trenger å finne et annet verktøy, ikke MS Word, og til dette formålet passer Markdown utmerket.

Markdown er et enkelt markeringsspråk. Det er ment for å lage vakkert utformede tekster i vanlige TXT-filer. Hvis vi lager dokumentene våre i Markdown, virker kombinasjonen av Markdown og Git naturlig.

Og alt ville være bra, og på dette punktet kunne vi ha satt punktum, hvis det ikke hadde vært vårt andre vilkår: «på utgangen trenger vi et dokument i et bestemt format, med bedriftsattributter, laget etter en bestemt mal» (og vi ble enige om i begynnelsen at for klarhetens skyld, ville dette være MS Word). Det vil si, hvis vi har bestemt oss for å bruke Markdown, så må vi på en eller annen måte konvertere denne filen til .docx i ønsket format.

Det finnes konverteringsprogrammer mellom forskjellige formater, for eksempel, Pandoc.
Du kan konvertere en Markdown-fil til .docx-format med dette programmet.
Men man må likevel forstå at, for det første, ikke alt som finnes i Markdown vil bli konvertert til MS Word, og for det andre, MS Word er et helt land sammenlignet med den strømlinjeformede, men likevel lille byen Markdown. Det finnes en enorm mengde funksjoner som finnes i Word og som ikke er tilgjengelige i noen form i Markdown. Du kan ikke bare ta og med bestemte nøkler konvertere Markdown-formatet ditt til ønsket MS Word-format med Pandoc. Så vanligvis, etter konvertering, må man «finpusse» det resulterende .docx-dokumentet manuelt, noe som igjen kan være tidkrevende og føre til feil.

Hvis vi kunne skrive et skript som automatisk «fullførte» det som Pandoc ikke klarte — ville det vært den ideelle løsningen.

På grunn av ulikheten i funksjonaliteten mellom MS Word og Markdown generelt, tror jeg det er umulig å løse denne oppgaven, men kan det gjøres i forhold til spesifikke situasjoner, spesifikke krav? Min erfaring har vist at ja, det kan det gjøres, og det er sannsynligvis mulig for mange, eller kanskje til og med de fleste situasjoner.

Løsningen på et spesifikt problem

Så, i mitt tilfelle, etter å ha konvertert filen med Pandoc, måtte jeg manuelt gjøre ytterligere behandling av filene, nemlig

• legge til felt i Word med automatisk nummerering av overskrifter (caption) for tabeller og bilder
• endre stil for tabeller

Jeg fant ikke ut hvordan jeg kunne gjøre dette med standard (Pandoc) eller kjente midler. Derfor brukte jeg et python-skript med pywin32 pakken. Som et resultat fikk jeg full automatisering. Nå kan jeg konvertere Markdown-filen min til ønsket form av MS Word-dokument med én kommando.

Se detaljer her.

Kommentar

I am of course converting some abstract Markdown file in this example, but the exact same approach was applied to a "live" document, and the output was practically the same MS Word document that we previously received through manual formatting.

In general, with pywin32 we gain almost complete control over the MS Word document, allowing us to modify it and format it according to your corporate standard. Of course, these same goals could be achieved with other tools, such as VBA macros, but I found it more convenient to use Python.

The brief formula for this approach is:

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

It’s not that important what 'something' is. In my case, it was Pandoc and Python with pywin32. You might have different preferences, but what matters is that it is possible. And that is the main point of this article.

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

Prosessen

I think for many the formula given above is sufficient to understand how the documentation process can now be organized. But I usually focus on network engineers, so I will briefly show how the workflow now might look and how it differs from an approach that involves editing MS Word files.

For clarity, let's choose GitHub as the platform for working with Git. Then you need to 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 online and on Habr.

Assuming that four people are working on the documentation and you are one of them. Then four additional branches are created, for example, with the names of these people. Each works locally in their own branch and makes changes with all the necessary git commands.

Når du fullfører en bestemt oppgave, oppretter du en pull request, som initierer diskusjonen om endringene dine. Under diskusjonen kan det vise seg at du må legge til eller endre noe. I så fall gjør du de nødvendige endringene og lager en ny pull request. Til slutt blir endringene dine godkjent og slått sammen (merge) med master-grenen (eller avvist).

Selvfølgelig er dette en ganske generell beskrivelse. Jeg anbefaler at du spør utviklerne dine for å lage en detaljert prosess eller finner folk med erfaring. Men jeg vil merke at terskelen for å begynne med Git er ganske lav. Dette betyr ikke at protokollen er enkel, men du kan begynne med noe enkelt. Hvis du ikke vet noe om det, tror jeg at du kan bruke flere timer eller dager på å lære deg det og begynne å bruke det.

Hva er fordelen med denne tilnærmingen sammenlignet med prosessen beskrevet i eksempelet ovenfor?

Faktisk er prosessene ganske like, du har bare byttet ut

filkopiering -> oppretting av gren (branch)
kopiering av tekst til sluttfilen -> sammenslåing (merge)
kopiering av de nyeste endringene til deg -> git pull/fetch
diskusjon via melding -> pull requests
track modus -> git diff
siste godkjente versjon -> master-gren
backup (kopiering til en ekstern server) -> git push
…

Dermed har du automatisert alt du allerede var tvunget til å gjøre manuelt.

På et høyere nivå lar det deg

• opprette en klar, enkel og kontrollert prosess for endringer i dokumentasjonen
• fordi det endelige dokumentet (i vårt eksempel MS Word) opprettes automatisk, reduserer det sjansen for formateringsfeil.

Kommentar

Gitt det ovenstående, er det tydelig at selv om du jobber med dokumentasjonen alene, kan bruken av Git betydelig lette arbeidet ditt.

Alt dette øker kvaliteten på dokumentasjonen og reduserer tiden brukt på å lage den. Og en liten bonus – du vil lære Git, noe som vil hjelpe deg med automatiseringen av nettverket ditt 🙂

Hvordan gå over til den nye prosessen?

I begynnelsen av artikkelen skrev jeg at du allerede i morgen kan begynne å jobbe på en ny måte. Hvordan kan du overføre arbeidet ditt til en ny retning?

Her er en sekvens av trinn du mest sannsynlig må følge:

• hvis dokumentet ditt er veldig stort, del det opp i deler
• konverter kvar del til Markdown (for eksempel med Pandoc)
• installer en av Markdown-editorene (jeg bruker Typora)
• du må sannsynligvis justere formateringen av de opprettede Markdown-dokumentene
• begynn å bruke prosessen beskrevet i forrige kapittel
• samtidig begynner du å modifisere konverteringsscriptet for din oppgave (eller lag noe eget)

Du trenger ikke vente med å lage og perfeksjonere mekanismen for konvertering fra Markdown til ønsket dokumentformat. Poenget er at selv om du ikke klarer å fullautomatisere prosessen for konvertering av Markdown-filene dine raskt, kan du fortsatt gjøre det på en eller annen måte ved hjelp av Pandoc og deretter finjustere det manuelt. Vanligvis trenger du ikke å gjøre dette ofte, og bare i slutten av bestemte faser, og dette manuelle arbeidet, selv om det kan være vanskelig, er likevel, etter min mening, ganske akseptabelt i feilsøkingsfasen og bør ikke «bremse» prosessen for mye.

Alt annet (Markdown, Git, Pandoc, Typora) er allerede klart og krever ikke spesielle anstrengelser eller tid for å begynne å jobbe med dem.

Kilde: habr.com