Uneori, nu doar documentația în sine, ci și procesul de lucru asupra acesteia poate fi critic. De exemplu, în cazul proiectelor, o mare parte din muncă este legată de pregătirea documentației, iar un proces greșit poate duce la erori și chiar la pierderea informațiilor, deci și la pierderi de timp și profit. Dar chiar dacă această temă nu este centrală în activitatea dumneavoastră și se află în periferie, un proces corect poate îmbunătăți calitatea documentului și vă poate economisi timp.
Abordarea prezentată aici, cu , prezintă un prag de accesibilitate scăzut. Tehnic, puteți începe să lucrați diferit chiar de mâine.
Formularea problemei
Trebuie să creați un document sau un set de documente. Poate că este documentația proiectului sau documentarea rețelei dumneavoastră, sau ceva mai simplu, de exemplu, trebuie să descrieți procesele din companie sau din departamentul dumneavoastră. În general, vorbim despre orice document sau set de documente cu text, imagini, tabele... Să complicăm sarcina având în vedere că
- această activitate implică colaborare, eforturi ale unui grup sau a mai multor grupuri de angajați
- la final doriți să aveți un document într-un format specific, cu atributele stilului corporativ, creat conform unui anumit șablon. Pentru a fi mai specific, să presupunem că este vorba despre MS Word (.docx)
Acum 10 ani, abordarea ar fi fost clară: am fi creat un document MS Word sau documente și am organizat în vreun fel munca de modificare.
Și această abordare este încă valabilă. Aceasta este folosită și de mari integratori pentru crearea documentației proiectului. Dar este intuitiv clar că, dacă lucrați intensiv, cu multe modificări și discuții, pe parcursul unei perioade îndelungate asupra unui document, această abordare nu este foarte convenabilă.
Exemplu
Am resimțit destul de acut această problemă lucrând pentru un mare integrator. Procesul de modificare a documentației proiectului era următorul:
- inginerul descarcă ultima versiune a documentului MS Word (.docx)
- schimbă titlul
- face modificări în modul de urmărire a modificărilor
- trimite documentul cu modificările arhitectului
- de asemenea, trimite lista tuturor corecțiilor cu comentarii
- arhitectul analizează schimbările
- dacă totul este bine, copiază modificările în fișierul cu ultima versiune, schimbă versiunea, îl încarcă pe resursa comună
- dacă există observații, se inițiază o discuție (email sau întâlniri)
- se atinge consensul
- apoi punctele 3 - 9
Până acum, activitatea nu a fost intensivă, așa că a funcționat cumva, dar totuși a funcționat. Totuși, într-un anumit moment, acest proces a devenit un loc strâmt al întregului proiect și a dus la probleme. Problema este că totul devine complicat când modificările sunt frecvente și sunt efectuate simultan de mai multe echipe.
Așadar, când am trecut la etapa de testare preliminară, au început să apară diverse probleme și, deși erau mărunte, a fost nevoie să modificăm frecvent documentația — patru echipe diferite, zilnic, practic simultan, cu discuții. Toate aceste modificări treceau printr-un inginer — arhitect. Fișierul cu designul proiectului era enorm și, ca urmare, arhitectul a fost sufocat de munca de rutină legată de un volum mare de copiere, editare, făcea multe greșeli, trebuia să verifice totul din nou, să redirecționeze, și în general, a fost aproape haos.
În acest caz, abordarea de lucru cu documentul MS Word a funcționat cu multă strânsoare și a creat probleme.
Git, Markdown
Înfruntând problema descrisă în exemplul de mai sus, am început să investighez acest subiect.
Am observat că devine din ce în ce mai popular să folosim împreună cu în crearea documentelor.
Git este un instrument pentru dezvoltare. Dar de ce să nu-l folosim pentru procesul de documentare? În acest caz, problema muncii multi-utilizator devine rezolvată. Dar pentru a profita la maxim de capacitățile Git, avem nevoie de un format text pentru document, trebuie să găsim un alt instrument, nu MS Word, iar pentru aceste scopuri, Markdown se potrivește perfect.
Markdown este un limbaj simplu de marcare a textului. Este destinat creării de texte frumos formatate în fișiere normale de format TXT. Dacă ne creăm documentele în Markdown, atunci legătura Markdown - Git devine naturală.
Și totul ar fi fost bine, iar în acest loc s-ar fi putut pune punct, dacă nu ar fi fost a doua condiție: „la ieșire avem nevoie de un document într-un anumit format, cu atributele stilului corporativ, creat după un anumit șablon” (și ne-am înțeles la început că, pentru claritate, acesta va fi MS Word). Adică, dacă am decis să folosim Markdown, atunci trebuie să transformăm acest fișier în .docx de forma necesară.
Există programe de conversie între diferite formate, de exemplu, .
Puteți converti fișierul Markdown în format .docx folosind acest program.
Dar, totuși, trebuie să înțelegem că, pe de o parte, nu tot ceea ce există în Markdown va fi convertit în MS Word și, pe de altă parte, MS Word este o întreagă lume comparativ cu orașul bine organizat numit Markdown. Există o mulțime de lucruri în Word care nu există în niciun fel în Markdown. Nu poți pur și simplu să iei și să convertești formatul tău Markdown în forma dorită în MS Word cu anumite chei în Pandoc. Așa că, de obicei, după conversie, trebuie să „finalizăm” documentul .docx obținut manual, ceea ce din nou poate fi consumator de timp și poate duce la erori.
Dacă am putea scrie un script care să „finalizeze” automat tot ceea ce nu a reușit Pandoc — ar fi soluția ideală.
Având în vedere că funcționalitatea MS Word și Markdown nu sunt identice în general, consider că a rezolva această sarcină este imposibil, dar se poate face în raport cu situații concrete, cerințe specifice? Experiența mea a arătat că da, este posibil și cel mai probabil aceasta este posibilă pentru multe sau poate chiar majoritatea situațiilor.
Rezolvarea unei probleme specifice
Astfel, în cazul meu, după conversia fișierului cu ajutorul Pandoc, a trebuit să fac manual procesarea suplimentară a fișierelor, și anume
- să adaug în Word câmpuri cu număr de capitole automat (caption) pentru tabele și imagini
- să schimb stilul pentru tabele
Nu am găsit o modalitate de a face acest lucru cu standardele (Pandoc) sau instrumentele cunoscute. De aceea, am aplicat un script Python cu pachet. Ca rezultat, am obținut o automatizare completă. Acum pot converti fișierul meu Markdown în forma dorită a documentului MS Word cu o singură comandă.
Vezi detalii .
Observație
În acest exemplu, desigur, voi transforma un fișier Markdown abstract, însă aceeași abordare a fost aplicată unui document 'de lucru', iar la final am obținut practic același document MS Word pe care îl obțineam anterior prin formatarea manuală.
În general, cu pywin32 obținem practic un control total asupra documentului MS Word, ceea ce ne permite să-l modificăm și să-l aducem la aspectul cerut de standardul dumneavoastră corporativ. Desigur, aceste obiective ar fi putut fi atinse și cu alte instrumente, cum ar fi macrocomenzile VBA, dar mi-a fost mai comod să folosesc python.
Formula scurtă a acestei abordări este:
Markdown + Git -- (ceva) --> MS WordNu este atât de important ce reprezintă 'ceva'. În cazul meu, a fost Pandoc și python cu pywin32. Poate că aveți alte preferințe, dar ceea ce contează este că este posibil. Iar acesta este mesajul principal al acestui articol.
În concluzie, ideea este că prin această abordare lucrați doar cu fișierul Markdown și folosiți Git pentru a organiza colaborarea și controlul versiunilor, iar doar atunci când este necesar (de exemplu, pentru a oferi documentația clientului) creați automat fișierul în formatul dorit (de exemplu, MS Word).
Procesul
Cred că pentru mulți formula prezentată mai sus este suficientă pentru a înțelege cum poate fi organizat acum procesul de lucru cu documentația. Totuși, de obicei mă orientez spre inginerii de rețea, așa că voi prezenta în linii mari cum ar putea arăta acum procesul de lucru și cu ce se diferențiază acesta de abordarea de editare a fișierelor MS Word.
Pentru a fi clar, vom alege GitHub ca platformă pentru a lucra cu Git. Așadar, trebuie să creați un repository și, în ramura master, să plasați fișierul sau fișierele Markdown cu care intenționați să lucrați.
Vom examina un proces simplu, bazat pe 'github flow'. O descriere poate fi găsită atât pe internet, cât și pe .
Să presupunem că documentația este elaborată de patru persoane și dumneavoastră sunteți una dintre ele. Atunci se creează patru ramuri suplimentare (branch), de exemplu, cu numele acestor persoane. Fiecare lucrează local, în ramura sa și face modificări folosind toate .
Cu un anumit fragment de muncă finalizat, creați un pull request, inițiind astfel discuția despre modificările dumneavoastră. Este posibil ca, în procesul de discuție, să se descopere că trebuie să adăugați sau să schimbați ceva. În acest caz, faceți modificările necesare și creați un alt pull request. În cele din urmă, modificările dumneavoastră sunt acceptate și îmbinate (merge) cu ramura master (sau respinse).
Desigur, aceasta este o descriere destul de generală. Vă sugerez să abordați dezvoltatorii dumneavoastră sau să găsiți persoane competente pentru a crea un proces detaliat. Dar doresc să subliniez că pragul de intrare în Git este destul de scăzut. Asta nu înseamnă că protocolul este simplu, dar puteți începe cu lucruri simple. Dacă nu știți nimic, cred că, dedicând câteva ore sau poate zile pentru studiu și instalare, puteți începe să-l folosiți.
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, doar că ați înlocuit
copierea fișierului -> crearea unei ramuri (branch)
copierea textului în fișierul final -> îmbinarea (merge)
copierea modificărilor recente către dumneavoastră -> git pull/fetch
discuția în corespondență -> pull requests
mod de urmărire -> git diff
ultima versiune aprobată -> ramura master
backup (copiere pe un server extern) -> git push
…
Astfel, ați automatizat tot ceea ce trebuia să faceți manual.
La un nivel mai înalt, acest lucru vă permite
- să creați un proces clar, simplu și controlat pentru modificările documentației
- deoarece documentul final (în exemplul nostru MS Word) este generat automat, această abordare reduce riscul de erori legate de formatare
Observație
Având în vedere cele de mai sus, cred că este evident că, chiar dacă lucrați singur la documentație, utilizarea Git poate să vă ușureze considerabil munca
Toate acestea îmbunătățesc calitatea documentației și reduc timpul necesar pentru crearea acesteia. Și încă un mic bonus — veți învăța Git, ceea ce vă va ajuta în automatizarea rețelei dumneavoastră 🙂
Cum să treceți la un nou proces?
La începutul articolului am menționat că puteți începe să lucrați diferit de mâine. Cum să vă redirecționați munca?
Iată secvența de pași pe care va trebui, cel mai probabil, să o urmați:
- dacă documentul dumneavoastră este foarte mare, împărțiți-l în părți
- converteți fiecare parte în Markdown (de exemplu, folosind Pandoc)
- instalați unul dintre editorii Markdown (eu folosesc )
- probabil va trebui să ajustați formatarea documentelor Markdown create
- începeți să aplicați procesul descris în capitolul anterior
- în paralel, începeți să modificați scriptul de conversie pentru nevoile dumneavoastră (sau creați ceva propriu)
Nu trebuie să așteptați până când ați creat și debug-uit perfect mecanismul de conversie Markdown -> aspectul necesar al documentului. Chiar dacă nu reușiți să automatizați rapid complet procedura pentru fișierele dumneavoastră Markdown, veți putea totuși face acest lucru într-o formă oarecare cu Pandoc și apoi să-l aduceți manual la forma finală. De obicei, nu trebuie să faceți acest lucru frecvent, ci doar la finalul anumitor etape, și această muncă manuală, deși incomodă, este, în opinia mea, acceptabilă în etapa de debugging și nu ar trebui să „blocheze” prea mult procesul.
Tot restul (Markdown, Git, Pandoc, Typora) este deja pregătit și nu necesită eforturi sau timp deosebit pentru a începe să lucrați cu ele.
Sursa: habr.com
