Folosiți GIT când vă documentați

Uneori, nu numai documentația în sine, ci și procesul de lucru asupra acesteia pot fi critice. De exemplu, în cazul proiectelor, cea mai mare parte a lucrării este legată de pregătirea documentației, iar un proces incorect poate duce la erori și chiar pierderi de informații și, în consecință, pierderi de timp și de beneficii. Dar chiar dacă acest subiect nu este esențial pentru munca dvs. și este la periferie, procesul corect poate încă îmbunătăți calitatea documentului și vă poate economisi timp.

Abordarea prezentată aici, cu exemplu de implementare specifică, are o barieră scăzută de intrare. Din punct de vedere tehnic, puteți începe să lucrați într-un mod nou mâine.

Declarație de problemă

Trebuie să creați un document sau un set de documente. Poate că aceasta este documentația de proiect sau înregistrarea rețelei dvs. sau ceva mai simplu, de exemplu, trebuie să descrieți procesele din companie sau din departamentul dvs. În general, vorbim despre orice document sau set de documente cu text, imagini, semne... Să complicăm sarcina prin faptul că

1. aceasta munca presupune munca in comun, eforturile unui grup sau mai multor grupuri de angajati
2. Ca urmare, doriți să aveți un document într-un anumit format, cu atribute de stil corporativ, creat după un anumit șablon. Pentru a fi specific, vom presupune că acesta este MS Word (.docx)

Acum 10 ani, abordarea ar fi fost simplă: am fi creat un document sau documente MS Word și am fi organizat cumva munca de schimbare.

Și această abordare este încă valabilă. De asemenea, este folosit de marii integratori atunci când creează documentația de proiect. Dar este intuitiv clar că, dacă lucrezi cu adevărat intens la un document, cu multe editări și discuții, pe o perioadă lungă de timp, această abordare nu este foarte convenabilă.

Exemplu

Am simțit această problemă destul de acut în timp ce lucram pentru un integrator mare. Procesul de modificare a documentației de proiectare a fost următorul:

1. inginerul descarcă cea mai recentă versiune a documentului MS Word (.docx).
2. schimba numele
3. face modificări pentru a urmări moda
4. trimite arhitectului documentul cu editări
5. trimite, de asemenea, o listă cu toate corecțiile cu comentarii
6. arhitectul analizează schimbările
7. dacă totul este bine, copiază aceste modificări într-un fișier cu cea mai recentă versiune, schimbă versiunea și o încarcă într-o resursă partajată
8. dacă există comentarii, se inițiază o discuție (e-mail sau întâlniri)
9. se ajunge la consens
10. alte puncte 3 - 9

Deși munca nu a fost intensă, a fost cumva, dar a funcționat totuși. Dar, la un moment dat, acest proces a devenit blocajul întregului proiect și a dus la probleme. Ideea este că lucrurile se înrăutățesc de îndată ce schimbările sunt făcute frecvent și simultan de mai multe echipe.

Așa că, când am trecut la stadiul de testare preliminară, au început să apară diverse probleme și, deși în mici dimensiuni, a fost necesară schimbarea des documentației - patru echipe diferite, în fiecare zi, aproape simultan, cu discuții. Toate aceste schimbări au avut loc printr-un singur inginer - un arhitect. Fișierul de proiectare a proiectului a fost uriaș și, ca urmare, arhitectul a fost copleșit de lucrări de rutină asociate cu multă copiere, editare, a făcut multe greșeli, a trebuit să verifice totul, să-l retrimite și, în general, a fost aproape spre haos.

În acest caz, această abordare, abordarea lucrului pe un document MS Word, a funcționat cu mare dificultate și a creat probleme.

Git, Markdown

Confruntat cu problema descrisă în exemplul de mai sus, am început să cercetez această problemă.
Am văzut că folosirea Reduceri impreuna cu merge la crearea documentelor.

Git este un instrument de dezvoltare. Dar de ce să nu-l folosești pentru procesul de documentare? În acest caz, problema muncii cu mai mulți utilizatori devine rezolvată. Dar pentru a profita din plin de capacitățile Git, avem nevoie de un format de document text, trebuie să găsim un alt instrument decât MS Word, iar Markdown este excelent pentru aceste scopuri.

Markdown este un limbaj simplu de marcare a textului. Este conceput pentru a crea texte frumos proiectate în fișiere TXT obișnuite. Dacă ne creăm documentele în Markdown, atunci combinația Markdown - Git pare naturală.

Și totul ar fi bine, iar în acest moment am putea pune capăt, dacă nu ar fi a doua noastră condiție: „în consecință, avem nevoie de un document într-un anumit format, cu atributele unui stil corporativ, creat conform un anumit șablon” (și am convenit la început că pentru Cu siguranță va fi MS Word). Adică, dacă decidem să folosim Markdown, atunci trebuie să convertim cumva acest fișier într-un .docx de tipul necesar.

Există programe pentru conversia între diferite formate, de ex. pandoc.
Puteți converti fișierul Markdown în format .docx cu acest program.
Dar totuși, trebuie să înțelegeți că, în primul rând, nu tot ce este în Markdown va fi convertit în MS Word și, în al doilea rând, MS Word este o țară întreagă în comparație cu orașul zvelt, dar încă mic, Markdown. Există o cantitate imensă de tot ce este în Word, care nu este sub nicio formă în Markdown. Nu puteți pur și simplu să vă convertiți formatul Markdown în formatul MS Word dorit folosind anumite taste Pandoc. Deci, de obicei, după conversie, trebuie să „editați” manual documentul .docx rezultat, ceea ce, din nou, poate consuma mult timp și poate duce la erori.

Dacă am putea scrie un script care să „termine” automat ceea ce Pandoc nu a putut face față, aceasta ar fi o soluție ideală.

Din cauza neidentității funcționalității MS Word și Markdown, cred că este imposibil de rezolvat această problemă în termeni generali, dar se poate face acest lucru în raport cu situații specifice, cerințe specifice? Experiența mea a arătat că da, este posibil și cel mai probabil este posibil pentru multe, sau poate chiar pentru majoritatea situațiilor.

Rezolvarea unei anumite probleme

Deci, în cazul meu, după convertirea fișierului folosind Pandoc, a trebuit să fac manual procesare suplimentară a fișierului, și anume

• adăugați câmpuri la Word cu numerotarea automată a titlurilor (titlurilor) tabelelor și imaginilor
• schimba stilul mesei

Nu am găsit cum să fac asta folosind mijloace standard (Pandoc) sau cunoscute. Așa că am aplicat scriptul python cu pywin32 pachet. Drept urmare, am obținut o automatizare completă. Acum îmi pot converti fișierul Markdown în formularul de document MS Word dorit cu o singură comandă.

Vezi detalii aici.

remarcă

În acest exemplu, desigur, convertesc un fișier Markdown abstract, dar exact aceeași abordare a fost aplicată documentului „de luptă”, iar rezultatul primit a fost aproape exact același document MS Word pe care l-am primit anterior prin formatare manuală. .

În general, cu pywin32 obținem un control aproape complet asupra documentului MS Word, ceea ce ne permite să-l schimbăm și să-l aducem la forma pe care o cere standardul dumneavoastră corporativ. Desigur, aceleași obiective puteau fi atinse folosind alte instrumente, de exemplu, macrocomenzi VBA, dar mi-a fost mai convenabil să folosesc python.

O scurtă formulă pentru această abordare:

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

Nu contează ce este „ceva”. În cazul meu a fost Pandoc și python cu pywin32. Preferințele tale pot fi diferite, dar important este că este posibil. Și acesta este mesajul principal al acestui articol.

Pentru a rezuma, ideea este că prin această abordare se lucrează doar cu fișierul Markdown și se folosește Git pentru colaborare și controlul versiunilor și numai atunci când este necesar (de exemplu, pentru a oferi documentație clientului) creați automat un fișier în formatul dorit ( de exemplu, MS Word).

proces

Cred că pentru mulți, formula dată mai sus este suficientă pentru a înțelege cum se poate organiza acum procesul de lucru cu documentația. Dar totuși, de obicei mă concentrez pe inginerii de rețea, așa că voi arăta în termeni generali cum poate arăta acum procesul de lucru și cum diferă acest lucru de abordarea de editare a fișierelor MS Word.

Pentru a fi specific, vom alege GitHub ca platformă pentru lucrul cu Git. Apoi ar trebui să creați un depozit și să plasați fișierul Markdown sau fișierele cu care intenționați să lucrați în ramura principală.

Ne vom uita la un proces simplu bazat pe „fluxul github”. Descrierea acestuia poate fi găsită atât pe Internet, cât și pe habre.

Să presupunem că sunt patru oameni care lucrează la documentație și tu ești unul dintre ei. Apoi sunt create patru ramuri suplimentare, de exemplu, cu numele acestor persoane. Fiecare lucrează la nivel local, în propria ramură și face schimbări cu tot ce este necesar comenzile git.

După ce ați finalizat o lucrare finalizată, creați o cerere de extragere, inițiind astfel o discuție despre modificările dvs. Poate că, în timpul discuției, se dovedește că ar trebui să adaugi sau să schimbi altceva. În acest caz, faceți modificările necesare și creați o cerere de extragere suplimentară. În cele din urmă, modificările dvs. sunt acceptate și îmbinate în ramura principală (sau eliminate).

Desigur, aceasta este o descriere destul de generală. Pentru a crea un proces detaliat, vă sugerez să vă contactați dezvoltatorii sau să găsiți persoane cu cunoștințe. Dar vreau să remarc că bariera de intrare în Git este destul de scăzută. Acest lucru nu înseamnă că protocolul este simplu, dar puteți începe simplu. Dacă nu știi absolut nimic, cred că după ce ai petrecut câteva ore sau poate zile învățând și instalând, poți începe să-l folosești.

Care este beneficiul acestei abordări în comparație, de exemplu, cu procesul descris în exemplul de mai sus?

De fapt, procesele sunt destul de asemănătoare, tocmai ați înlocuit

copierea unui fișier -> crearea unei ramuri
copierea textului în fișierul final -> îmbinare
copierea celor mai recente modificări către tine -> git pull/fetch
discuție în corespondență -> pull requests
track mode -> git diff
ultima versiune aprobată -> ramură principală
backup (copiere pe un server la distanță) -> git push
...

Astfel, ai automatizat tot ceea ce aveai deja de făcut, dar manual.

La un nivel superior îți permite

• creați un proces clar, simplu și controlat pentru modificările documentelor
• deoarece creați automat documentul final (în exemplul nostru MS Word), acest lucru reduce probabilitatea erorilor de formatare

remarcă

Acestea fiind spuse, cred că este evident că, chiar dacă lucrați doar la documentare, utilizarea Git vă poate ușura mult munca.

Toate acestea îmbunătățesc calitatea documentației și reduc timpul pentru crearea acesteia. Și încă un mic bonus - vei învăța Git, care te va ajuta la automatizarea rețelei :)

Cum se trece la un proces nou?

La începutul articolului, am scris că de mâine poți începe să lucrezi într-un mod nou. Cum să-ți duci munca într-o nouă direcție?

Iată secvența de pași pe care cel mai probabil va trebui să-i urmezi:

• dacă documentul este foarte mare, împărțiți-l în părți
• convertiți fiecare parte în Markdown (folosind Pandoc, de exemplu)
• instalați unul dintre editorii Markdown (eu folosesc Typora)
• cel mai probabil va trebui să ajustați formatarea documentelor Markdown create
• începeți să aplicați procesul descris în capitolul anterior
• în același timp, începeți să modificați scriptul de conversie pentru a se potrivi sarcinii dvs. (sau creați ceva propriu)

Nu trebuie să așteptați până când ați creat și perfecționat mecanismul de conversie Markdwon -> tipul de ieșire necesar de document. Ideea este că, chiar dacă nu reușiți să automatizați rapid procedura de conversie a fișierelor dvs. Markdown, puteți să o faceți într-o anumită formă folosind Pandoc și apoi să o aduceți manual în forma finală. De obicei, nu trebuie să faceți acest lucru des, ci doar la sfârșitul anumitor etape, iar această muncă manuală, deși incomod, este încă, după părerea mea, destul de acceptabilă în etapa de depanare și nu ar trebui să „încetinească” procesul mult.

Orice altceva (Markdown, Git, Pandoc, Typora) este deja gata și nu necesită mult efort sau timp pentru a începe să lucrezi cu ele.

Sursa: www.habr.com