Brug GIT ved dokumentation

Nogle gange kan ikke kun selve dokumentationen, men også processen med at arbejde med den være kritisk. I tilfælde af projekter er broderparten af ​​arbejdet for eksempel relateret til udarbejdelse af dokumentation, og en forkert proces kan føre til fejl og endda tab af information og dermed tab af tid og fordele. Men selvom dette emne ikke er centralt for dit arbejde og er i periferien, kan den rigtige proces stadig forbedre kvaliteten af ​​dokumentet og spare dig tid.

Den her skitserede tilgang, med eksempel på en konkret implementering, har en lav adgangsbarriere. Teknisk set kan du begynde at arbejde på en ny måde i morgen.

Formulering af problemet

Du skal oprette et dokument eller et sæt dokumenter. Måske er det projektdokumentation eller logning af dit netværk, eller noget mere simpelt, for eksempel skal du beskrive processerne i virksomheden eller i din afdeling. Generelt taler vi om ethvert dokument eller sæt af dokumenter med tekst, billeder, skilte... Lad os komplicere opgaven ved at

1. dette arbejde involverer fælles arbejde, indsats fra en gruppe eller flere grupper af medarbejdere
2. Som et resultat vil du have et dokument i et bestemt format, med attributter for virksomhedsstil, oprettet i henhold til en bestemt skabelon. For at være specifikke vil vi antage, at dette er MS Word (.docx)

For 10 år siden ville tilgangen have været ligetil: vi ville have oprettet et eller flere MS Word-dokumenter og på en eller anden måde organiseret forandringsarbejdet.

Og denne tilgang er stadig gyldig. Det bruges også af store integratorer, når de opretter projektdokumentation. Men det er intuitivt klart, at hvis du virkelig arbejder intensivt på et dokument, med mange redigeringer og diskussioner, over en længere periode, er denne tilgang ikke særlig praktisk.

Eksempel

Jeg følte dette problem ret akut, mens jeg arbejdede for en stor integrator. Processen med at ændre designdokumentationen var som følger:

1. ingeniør downloader den seneste version af MS Word (.docx) dokument
2. skifter navn
3. foretager ændringer for at spore mode
4. sender dokumentet med redigeringer til arkitekten
5. sender også en liste over alle rettelser med kommentarer
6. arkitekt analyserer ændringer
7. hvis alt er godt, kopierer den disse ændringer til en fil med den seneste version, ændrer versionen og uploader den til en delt ressource
8. hvis der er kommentarer, indledes en diskussion (e-mail eller møder)
9. konsensus opnås
10. yderligere punkt 3-9

Selvom arbejdet ikke var intenst, var det på en eller anden måde, men det virkede stadig. Men på et vist tidspunkt blev denne proces flaskehalsen i hele projektet og førte til problemer. Pointen er, at tingene bliver dårlige, så snart ændringer foretages hyppigt og samtidigt af flere hold.

Så da vi gik over til den indledende testfase, begyndte der at dukke forskellige problemer op, og selvom det var på små måder, var det nødvendigt at ændre dokumentationen ofte - fire forskellige hold, hver dag, næsten samtidigt, med diskussioner. Alle disse ændringer fandt sted gennem én ingeniør - en arkitekt. Projektdesignfilen var enorm, og som et resultat blev arkitekten overvældet af rutinearbejde, der involverede en masse kopiering, redigering, lavede en masse fejl, skulle dobbelttjekke alt, sende det igen, og generelt var det tæt på kaos.

I dette tilfælde fungerede denne tilgang, tilgangen til at arbejde på et MS Word-dokument, med stor besvær og skabte problemer.

Git, Markdown

Stillet over for problemet beskrevet i eksemplet ovenfor, begyndte jeg at undersøge dette problem.
Jeg så, at brugen af markdown sammen med Git ved oprettelse af dokumenter.

Git er et udviklingsværktøj. Men hvorfor ikke bruge det til dokumentationsprocessen? I dette tilfælde bliver problemet med flerbrugerarbejde løst. Men for at drage fuld fordel af Gits muligheder, har vi brug for et tekstdokumentformat, vi skal finde et andet værktøj end MS Word, og Markdown er fantastisk til disse formål.

Markdown er et simpelt tekstopmærkningssprog. Den er designet til at skabe smukt designede tekster i almindelige TXT-filer. Hvis vi opretter vores dokumenter i Markdown, så ser Markdown - Git kombinationen naturlig ud.

Og alt ville være fint, og på dette tidspunkt kunne vi sætte en stopper for det, hvis ikke for vores anden betingelse: "som følge heraf har vi brug for et dokument i et bestemt format, med egenskaberne af en virksomhedsstil, oprettet iht. en bestemt skabelon” (og vi aftalte i begyndelsen, at det bestemt bliver MS Word). Det vil sige, hvis vi beslutter os for at bruge Markdown, så skal vi på en eller anden måde konvertere denne fil til en .docx af den påkrævede type.

Der findes programmer til konvertering mellem forskellige formater, f.eks. Pandoc.
Du kan konvertere Markdown-fil til .docx-format med dette program.
Men alligevel skal du forstå, at for det første vil ikke alt, der er i Markdown, blive konverteret til MS Word, og for det andet er MS Word et helt land sammenlignet med den slanke, men stadig lille by, Markdown. Der er en enorm mængde af alt, der er i Word, som ikke er i nogen form i Markdown. Du kan ikke bare gå videre og konvertere dit Markdown-format til det ønskede MS Word-format ved hjælp af visse Pandoc-taster. Så normalt, efter konvertering, skal du "redigere" det resulterende .docx-dokument manuelt, hvilket igen kan være tidskrævende og føre til fejl.

Hvis vi kunne skrive et script, der automatisk ville "færdiggøre" det, Pandoc ikke kunne håndtere, ville det være en ideel løsning.

På grund af manglende identitet i funktionaliteten af ​​MS Word og Markdown, er det umuligt at løse dette problem generelt, tror jeg, men kan dette lade sig gøre i forhold til specifikke situationer, specifikke krav? Min erfaring har vist, at ja, det er muligt og højst sandsynligt er det muligt i mange, eller måske endda de fleste situationer.

Løsning af et bestemt problem

Så i mit tilfælde, efter at have konverteret filen ved hjælp af Pandoc, måtte jeg manuelt udføre yderligere filbehandling, nemlig

• tilføje felter til Word med automatisk nummerering af overskrifter (billedtekster) af tabeller og billeder
• ændre bordstil

Jeg har ikke fundet, hvordan man gør dette ved hjælp af standard (Pandoc) eller kendte midler. Så jeg anvendte python-scriptet med pywin32 pakke. Som et resultat fik jeg fuld automatisering. Nu kan jeg konvertere min Markdown-fil til den ønskede MS Word-dokumentform med én kommando.

Se detaljer her.

bemærkning

I dette eksempel konverterer jeg selvfølgelig en eller anden abstrakt Markdown-fil, men nøjagtig den samme tilgang blev anvendt på "kamp"-dokumentet, og det output, jeg modtog, var næsten nøjagtigt det samme MS Word-dokument, som vi tidligere havde modtaget ved manuel formatering .

Generelt får vi med pywin32 næsten fuldstændig kontrol over MS Word-dokumentet, hvilket giver os mulighed for at ændre det og bringe det til den form, som din virksomhedsstandard kræver. Selvfølgelig kunne de samme mål opnås ved hjælp af andre værktøjer, for eksempel VBA-makroer, men det var mere bekvemt for mig at bruge python.

En kort formel for denne tilgang:

Markdown + Git -- (нечто) --> MS Word

Det er lige meget, hvad "noget" er. I mit tilfælde var det Pandoc og python med pywin32. Dine præferencer kan være anderledes, men det vigtige er, at det er muligt. Og dette er hovedbudskabet i denne artikel.

For at opsummere er tanken, at man med denne tilgang kun arbejder med Markdown-filen og bruger Git til samarbejde og versionskontrol, og kun når det er nødvendigt (for eksempel for at levere dokumentation til klienten) automatisk oprette en fil i det ønskede format ( for eksempel MS Word).

Процесс

Jeg tror, ​​at for mange er ovenstående formel tilstrækkelig til at forstå, hvordan processen med at arbejde med dokumentation nu kan organiseres. Men alligevel plejer jeg at fokusere på netværksingeniører, så jeg vil i generelle vendinger vise, hvordan arbejdsprocessen nu kan se ud, og hvordan denne adskiller sig fra tilgangen til redigering af MS Word-filer.

For at være specifik vil vi vælge GitHub som platformen til at arbejde med Git. Derefter skal du oprette et lager og placere den eller de Markdown-filer, du planlægger at arbejde med, i mastergrenen.

Vi vil se på en simpel proces baseret på "github flow". Dens beskrivelse kan findes både på internettet og på habre.

Lad os sige, at der er fire personer, der arbejder på dokumentationen, og at du er en af ​​dem. Derefter oprettes fire yderligere grene, for eksempel med navnene på disse personer. Alle arbejder lokalt, i deres egen afdeling og laver ændringer med alt det nødvendige git kommandoer.

Når du har afsluttet et eller andet afsluttet stykke arbejde, opretter du en pull-anmodning, hvorved du starter en diskussion af dine ændringer. Måske viser det sig under diskussionen, at du skal tilføje eller ændre noget andet. I dette tilfælde foretager du de nødvendige ændringer og opretter en ekstra pull-anmodning. Til sidst accepteres dine ændringer og flettes ind i mastergrenen (eller kasseres).

Dette er selvfølgelig en ret generel beskrivelse. For at skabe en detaljeret proces, foreslår jeg, at du kontakter dine udviklere eller finder kyndige personer. Men jeg vil bemærke, at barrieren for adgang til Git er ret lav. Dermed ikke sagt, at protokollen er enkel, men du kan starte enkelt. Hvis du ikke ved noget som helst, tror jeg, efter at have brugt et par timer eller måske dage på at lære og installere, kan du begynde at bruge det.

Hvad er fordelen ved denne tilgang sammenlignet med for eksempel processen beskrevet i eksemplet ovenfor?

Faktisk er processerne ret ens, du har lige udskiftet

kopiere en fil -> oprette en filial
kopiering af tekst til den endelige fil -> fletning
kopiere de seneste ændringer til dig selv -> git pull/fetch
diskussion i korrespondance -> pull anmodninger
track mode -> git diff
seneste godkendte version -> master branch
backup (kopierer til en ekstern server) -> git push
...

Således automatiserede du alt, hvad du allerede skulle gøre, men manuelt.

På et højere niveau giver det dig mulighed

• skabe en overskuelig, enkel og kontrolleret proces for dokumentændringer
• fordi du opretter det endelige dokument (i vores eksempel MS Word) automatisk, dette reducerer sandsynligheden for formateringsfejl

bemærkning

Når det er sagt, så synes jeg, det er indlysende, at selvom du arbejder med dokumentation alene, så kan brugen af ​​Git gøre dit arbejde meget lettere.

Alt dette forbedrer kvaliteten af ​​dokumentationen og reducerer tiden til dens oprettelse. Og en anden lille bonus - du vil lære Git, som vil hjælpe dig, når du automatiserer dit netværk :)

Hvordan skifter man til en ny proces?

I begyndelsen af ​​artiklen skrev jeg, at i morgen kan du begynde at arbejde på en ny måde. Hvordan tager du dit arbejde i en ny retning?

Her er rækkefølgen af ​​trin, du højst sandsynligt skal følge:

• hvis dit dokument er meget stort, opdel det i dele
• konverter hver del til Markdown (ved at bruge Pandoc for eksempel)
• installer en af ​​Markdown-editorerne (jeg bruger Typora)
• højst sandsynligt bliver du nødt til at justere formateringen af ​​de oprettede Markdown-dokumenter
• begynde at anvende processen beskrevet i forrige kapitel
• på samme tid skal du begynde at ændre konverteringsscriptet, så det passer til din opgave (eller oprette noget af dit eget)

Du behøver ikke vente, indtil du har oprettet og perfektioneret Markdwon-konverteringsmekanismen -> den påkrævede outputtype af dokument. Pointen er, at selvom du ikke er i stand til hurtigt fuldt ud at automatisere proceduren for konvertering af dine Markdown-filer, kan du stadig gøre det i en eller anden form ved hjælp af Pandoc og derefter bringe det til den endelige form manuelt. Normalt behøver du ikke at gøre dette ofte, men kun i slutningen af ​​visse faser, og dette manuelle arbejde, selvom det er ubelejligt, er efter min mening stadig ganske acceptabelt på fejlretningsstadiet og bør ikke "sænke" processen meget.

Alt andet (Markdown, Git, Pandoc, Typora) er allerede klar og kræver ikke meget indsats eller tid for at begynde at arbejde med dem.

Kilde: www.habr.com