Dažreiz ne tikai pati dokumentācija, bet arī darba process, kas saistīts ar to, var būt kritisks. Piemēram, projektu gadījumā lielākā daļa darba ir saistīta tieši ar dokumentācijas sagatavošanu, un nepareizs process var novest pie kļūdām un pat datu zaudēšanas, kas, savukārt, noved pie laika un peļņas zaudēšanas. Bet pat ja šī tēma nav centrāla jūsu darbā un atrodas perifērijā, pareizais process joprojām var uzlabot dokumenta kvalitāti un ietaupīt jums laiku.
Šeit izklāstītā pieeja, , ir ar zemu uzņemšanas slieksni. Tehniski, jau rīt jūs varat sākt strādāt pa jaunu.
Uzdevuma formulēšana
Jums ir nepieciešams izveidot kādu dokumentu vai dokumentu kopumu. Iespējams, tas ir projekta dokumentācija vai tīkla protokolēšana, vai kas vienkāršāks, piemēram, jums ir jāsakārto procesi uzņēmumā vai jūsu nodaļā. Kopumā tas attiecas uz jebkuru dokumentu vai dokumentu kopumu, kas satur tekstu, attēlus, tabulas... Apgrūtināsim uzdevumu ar to, ka
- šis darbs paredz kopīgu darbu, grupas vai vairāku grupu darbinieku pūles
- un gala rezultātā vēlaties, lai jums būtu dokuments noteiktā formātā, ar korporatīvā stila atribūtiem, izveidots pēc noteikta šablona. Lai precizētu, pieņemsim, ka tas ir MS Word (.docx)
Pirms 10 gadiem pieeja būtu nepārprotama: mēs izveidotu MS Word dokumentu vai dokumentus un kaut kā organizētu izmaiņu darbu.
Un šāda pieeja joprojām ir spēkā. To izmanto, tostarp, arī lielie integratori projekta dokumentācijas izveidē. Taču ir skaidrs, ka, ja jūs tiešām intensīvi strādājat ar daudziem labojumiem un apspriedēm ilgstoši atkārtotā dokumentā, šī pieeja nav ļoti ērta.
uzbrukumam
Es ļoti izjustu šo problēmu, strādājot vienā lielā integratorā. Projekta dokumentācijas maiņas process bija šāds:
- inženieris lejupielādē pēdējo versiju MS Word (.docx) dokumenta
- maina nosaukumu
- veic labojumus track režīmā
- nosūta dokumentu ar labojumiem arhitektam
- tāpat nosūta visu izmaiņu sarakstu ar komentāriem
- arhitekts analizē izmaiņas
- ja viss ir labi, tad kopē šos datus jaunākajā versijā, maina versiju, publicē uz kopīgā resursa
- ja ir komentāri, tiek uzsākta diskusija (e-pasts vai meetings)
- tiek sasniegts konsenss
- tālāk punkti 3 — 9
Kamēr darbs nebija intensīvs, tas vairāk vai mazāk darbojās. Bet noteiktā brīdī šis process kļuva par šauru vietu visā projektā un radīja problēmas. Problēma ir tāda, ka viss sāk noiet greizi, tiklīdz izmaiņas tiek veiktas bieži un vienlaikus vairākām komandām.
Tātad, kad mēs pārgājām uz iepriekšējā testēšanas posmu, sāka izpausties dažādas problēmas un, lai arī tās bija sīkas, ik pa brīdim bija nepieciešams mainīt dokumentāciju — četras dažādas komandas, katru dienu, praktiski vienlaikus, ar apspriedēm. Visas šīs izmaiņas pārgāja cauri vienam inženierim — arhitektam. Projekta dizaina fails bija milzīgs, un kā rezultātā arhitekts bija pārpildīts ar rutīnas darbu, saistītu ar lielu daudzumu kopēšanas, rediģēšanas, izdarīja daudz kļūdu, bija jāpārbauda viss vēlreiz, jāpārsūta, un kopumā tas bija tuvu haosam.
Šajā gadījumā šī pieeja, strādājot ar MS Word dokumentu, darbojās ar lielām grūtībām un radīja problēmas.
Git, Markdown
Saskaroties ar iepriekš aprakstītajām problēmām, es sāku izpētīt šo jautājumu.
Es pamanīju, ka arvien populārāk kļūst izmantot kopā ar dokumentu veidošanā.
Git ir izstrādes rīks. Bet kāpēc to neizmantot dokumentēšanas procesā? Šajā gadījumā vairāku lietotāju darbs tiek atrisināts. Bet, lai pilnībā izmantotu Git iespējas, mums ir nepieciešams dokumenta teksta formāts, mums ir jāatrod cits rīks, nevis MS Word, un šim mērķim lieliski der Markdown.
Markdown ir vienkārša teksta marķēšanas valoda. Tā ir paredzēta, lai radītu skaisti noformētus tekstus parastos TXT formāta failos. Ja mēs veidosim savus dokumentus Markdown, tad saikne starp Markdown un Git izskatās dabiski.
Un viss būtu labi, un šajā vietā varētu ielikt punktu, ja vien nebūtu mūsu otrais nosacījums: „mums ir nepieciešams dokuments noteiktā formātā ar korporatīvā stila atribūtiem, izveidots pēc noteikta parauga” (un mēs sākumā vienojāmies, ka, lai būtu skaidrs, tas būs MS Word). Tātad, ja mēs nolēmām izmantot Markdown, tad mums jāspēj kādā veidā pārvērst šo failu .docx vajadzīgajā formātā.
Pastāv konvertēšanas programmas starp dažādām formām, piemēram, .
Jūs varat konvertēt Markdown failu .docx formātā ar šo programmu.
Tomēr ir jāņem vērā, ka, pirmkārt, ne viss, kas ir Markdown, tiks pārveidots MS Word, un, otrkārt, MS Word ir visa valsts salīdzinājumā ar sakārtoto, bet joprojām nelielo Markdown. Ir milzīgs daudzums funkcionalitātes, kas ir Word, un nav nekādas formas Markdown. Nav iespējams vienkārši ņemt un ar noteiktiem atslēgvārdiem Pandoc konvertēt jūsu Markdown formātu vēlamajā MS Word izskatā. Tāpēc parasti pēc konvertēšanas ir jāpabeidz saņemtā .docx dokumenta roka, kas atkal var būt laikietilpīga un radīt kļūdas.
Ja mēs varētu uzrakstīt skriptu, kas automātiski „pabeigtu” to, ar ko Pandoc netika galā - tas būtu ideāls risinājums.
Ņemot vērā MS Word un Markdown funkcionalitātes atšķirību vispār, domāju, ka šo problēmu risināt ir neiespējami, bet vai to var izdarīt attiecībā uz konkrētām situācijām un prasībām? Mans pieredze ir parādījusi, ka jā, tas ir iespējams un, visticamāk, tas ir iespējams daudziem, vai varbūt pat lielākajai daļai situāciju.
Konkrētas problēmas risinājums
Tātad, manā gadījumā, pēc faila konvertēšanas ar Pandoc man bija jārīkojas manuāli ar papildu failu apstrādi, proti,
- pievienot Word laukus ar automātisko virsrakstu numurēšanu (caption) tabulām un attēliem
- mainīt stilu tabulām
Es neatradu, kā to izdarīt ar standarta (Pandoc) vai zināmām sistēmām. Tāpēc es izmantoju python skriptu ar pakotni. Rezultātā es ieguvu pilnīgu automatizāciju. Tagad es varu konvertēt savu Markdown failu vajadzīgajā MS Word dokumenta formā ar vienu komandu.
Skatiet detaļas .
Piezīme
Šajā piemērā es, protams, pārveidoju kādu abstraktu Markdown failu, taču tieši tādu pašu pieeju esmu izmantojis «darba» dokumentā, un gala rezultātā es ieguvu praktiski tieši tādu pašu MS Word dokumentu, kuru iepriekš mēs saņēmām, manuāli formatējot.
Kopumā, izmantojot pywin32, mēs iegūstam praktiski pilnīgu kontroli pār MS Word dokumentu, kas ļauj to mainīt un pielāgot tādām prasībām, kādas ir jūsu korporatīvajam standartam. Protams, šos pašus mērķus varēja sasniegt, izmantojot citus rīkus, piemēram, VBA makros, taču man bija ērtāk izmantot Python.
Šī pieejas īsā formula:
Markdown + Git -- (kaut kas) --> MS WordNav tik svarīgi, kas ir «kaut kas». Manā gadījumā tas bija Pandoc un Python ar pywin32. Iespējams, jums ir citas preferences, taču svarīgi ir tas, ka tas ir iespējams. Un tas ir galvenais šīs raksta vēstījums.
Kopumā doma ir tāda, ka, izmantojot šo pieeju, jūs strādājat tikai ar Markdown failu un izmantojat Git, lai organizētu kopīgu darbu un kontrolētu versijas, un tikai nepieciešamības gadījumā (piemēram, lai sniegtu dokumentāciju klientam) automātiski izveidojat vajadzīgā formāta failu (piemēram, MS Word).
Process
Domāju, ka daudziem iepriekš minētā formula ir pietiekama, lai saprastu, kā tad tagad var organizēt dokumentācijas apstrādes procesu. Bet tomēr es parasti fokusējos uz tīkla inženieriem, tādēļ vispārīgi parādīšu, kā tagad varētu izskatīties darba process un kā tas atšķiras no pieejas, kurā rediģē MS Word failus.
Lai precizētu, kā platformu darbam ar Git izvēlēsimies GitHub. Tādā gadījumā jums jāizveido repozitorijs un master zarā jāievieto Markdown fails vai faili, ar kuriem plānojat strādāt.
Mēs apskatīsim vienkāršu procesu, kas balstīts uz «github flow». Tās aprakstu var atrast gan internetā, gan uz .
Pieņemam, ka pie dokumentācijas strādā četri cilvēki un jūs — viens no viņiem. Tādā gadījumā tiek izveidotas četras papildu zaras (branch), piemēram, ar šo cilvēku vārdiem. Katrs strādā lokāli, savā zarā un veic izmaiņas ar visām nepieciešamajām .
Izpildot kādu pabeigtu darbības daļu, jūs izveidojat pull request, tādējādi uzsākot diskusiju par jūsu izmaiņām. Iespējams, diskusijas procesā izrādīsies, ka jums jāpapildina vai jānomaina vēl kaut kas. Šajā gadījumā jūs veicat nepieciešamās izmaiņas un izveidojat papildu pull request. Galu galā jūsu izmaiņas tiek pieņemtas un apvienotas (merge) ar master zaru (vai noraidītas).
Protams, tas ir diezgan vispārīgs apraksts. Piedāvāju izstrādāt detalizētu procesu, sazinoties ar saviem izstrādātājiem vai meklējot zinošus cilvēkus. Bet gribu norādīt, ka Git iekļūšanas slieksnis ir diezgan zems. Tas nenozīmē, ka protokols ir vienkāršs, bet jūs varat sākt ar vienkāršu. Ja jūs vispār neko nezināt, domāju, ieguldot dažas stundas vai varbūt dienas mācīšanās un instalēšanas procesā, jūs varat sākt to lietot.
Kāda ir šī pieejas priekšrocība salīdzinājumā, piemēram, ar iepriekš minēto procesu?
Patiesībā procesi ir diezgan līdzīgi, jo jūs esat aizstājuši
faila kopēšanu -> zara (branch) izveidi
teksta kopēšanu gala failā -> apvienošanu (merge)
pēdējo izmaiņu kopēšanu sev -> git pull/fetch
diskusiju sarunās -> pull requests
izsekošanas režīmu -> git diff
pēdējo apstiprināto versiju -> master zaru
dublēšanu (failu kopēšanu uz attālo serveri) -> git push
…
Tādējādi jūs automatizējāt visu to, ko jums jau bija jāveic, bet manuāli.
Augstākā līmenī tas ļauj jums
- izveidot skaidru, vienkāršu un kontrolētu dokumentācijas izmaiņu procesu
- jo gala dokuments (mūsu piemērā MS Word) tiek izveidots automātiski, tas samazina kļūdu iespējamību, kas saistīta ar formatēšanu.
Piezīme
Ņemot vērā iepriekš minēto, domāju, ir acīmredzami, ka pat tad, ja jūs strādājat pie dokumentācijas viens, Git izmantošana var būtiski atvieglot darbu.
Tas viss uzlabo dokumentācijas kvalitāti un samazina laiku, kas nepieciešams tās izveidei. Un vēl viens mazs bonuss – jūs apgūsit Git, kas palīdzēs jums automatizēt jūsu tīklu 🙂
Kā pāriet uz jauno procesu?
Raksta sākumā es minēju, ka jau rīt jūs varat sākt strādāt jaunajā veidā. Kā pārcelt savu darbu jaunā gultnē?
Šeit ir soļu secība, ko jums, visticamāk, nāksies veikt:
- ja jūsu dokuments ir ļoti liels, sadaliet to daļās
- pārvērst katru daļu Markdown (piemēram, izmantojot Pandoc)
- uzstādiet vienu no Markdown redaktoriem (es izmantoju )
- visticamāk, jums būs jāpielāgo izveidoto Markdown dokumentu formatējums
- sāciet lietot iepriekšējā nodaļā aprakstīto procesu
- vienlaikus sāciet pārveidot konvertēšanas skriptu savām vajadzībām (vai izveidojiet kaut ko savu)
Nav nepieciešams gaidīt, līdz izstrādāsiet un perfektizēsiet Markdown konvertēšanas mehānismu uz vajadzīgo dokumenta formu. Jāatzīmē, ka pat ja jūs nevarat ātri pilnībā automatizēt procedūru, lai pārveidotu savus Markdown failus, jūs joprojām varēsiet to darīt kādā formā ar Pandoc un pēc tam manuāli pabeigt līdz galīgajai formai. Parasti jums nav nepieciešams to darīt bieži, tikai noteiktos posmos, un šī manuālā darba veikšana, kaut arī neērtā, ir pilnīgi pieļaujama debugēšanas posmā un nevajadzētu stipri "bremzēt" procesu.
Visi pārējie (Markdown, Git, Pandoc, Typora) jau ir gatavi un neprasa īpašas pūles vai laiku, lai sāktu ar tiem strādāt.
Avots: habr.com
