Uzu GIT dum dokumentado

Kelkfoje ne nur la dokumentado mem, sed ankaŭ la procezo labori pri ĝi povas esti kritika. Ekzemple, en la kazo de projektoj, la plej granda parto de la laboro rilatas al la preparado de dokumentado, kaj malĝusta procezo povas konduki al eraroj kaj eĉ perdo de informoj, kaj, sekve, perdo de tempo kaj profitoj. Sed eĉ se ĉi tiu temo ne estas centra en via laboro kaj estas en la periferio, la ĝusta procezo ankoraŭ povas plibonigi la kvaliton de la dokumento kaj ŝpari al vi tempon.

La aliro skizita ĉi tie, kun ekzemplo de specifa efektivigo, havas malaltan enirbarieron. Teknike, vi povas komenci labori en nova maniero morgaŭ.

Formulado de la problemo

Vi devas krei dokumenton aŭ aron de dokumentoj. Eble ĉi tio estas projektdokumentado aŭ protokolo de via reto, aŭ io pli simpla, ekzemple, vi devas priskribi la procezojn en la kompanio aŭ en via fako. Ĝenerale, ni parolas pri iu ajn dokumento aŭ aro da dokumentoj kun teksto, bildoj, signoj... Ni malfaciligu la taskon per tio, ke

1. ĉi tiu laboro implikas komunan laboron, la klopodojn de grupo aŭ pluraj grupoj de dungitoj
2. Kiel rezulto, vi volas havi dokumenton en certa formato, kun kompaniaj stilaj atributoj, kreita laŭ certa ŝablono. Por esti specifa, ni supozos, ke ĉi tio estas MS Word (.docx)

Antaŭ 10 jaroj la aliro estus simpla: ni estus kreintaj MS Word-dokumenton aŭ dokumentojn kaj iel organizintus la ŝanĝlaboron.

Kaj ĉi tiu aliro ankoraŭ validas. Ĝi ankaŭ estas uzata de grandaj integristoj dum kreado de projektodokumentado. Sed estas intuicie klare, ke se vi vere intense laboras pri dokumento, kun multaj redaktoj kaj diskutoj, dum longa tempo, ĉi tiu aliro ne estas tre oportuna.

Ekzemplo:

Mi sentis ĉi tiun problemon sufiĉe akute laborante por granda integristo. La procezo de ŝanĝado de la dezajnodokumentado estis kiel sekvas:

1. inĝeniero elŝutas la lastan version de MS Word (.docx) dokumento
2. ŝanĝas nomon
3. faras ŝanĝojn por spuri modon
4. sendas la dokumenton kun redaktoj al la arkitekto
5. ankaŭ sendas liston de ĉiuj korektoj kun komentoj
6. arkitekto analizas ŝanĝojn
7. se ĉio estas bona, ĝi kopias ĉi tiujn ŝanĝojn al dosiero kun la plej nova versio, ŝanĝas la version kaj alŝutas ĝin al komuna rimedo.
8. se estas komentoj, diskuto estas komencita (retpoŝto aŭ renkontiĝoj)
9. konsento estas atingita
10. pluaj punktoj 3 - 9

Dum la laboro ne estis intensa, ĝi estis iel, sed ĝi ankoraŭ funkciis. Sed ĉe certa punkto, ĉi tiu procezo iĝis la proplemkolo de la tuta projekto kaj kaŭzis problemojn. La punkto estas, ke aferoj malbonas tuj kiam ŝanĝoj estas faritaj ofte kaj samtempe de pluraj teamoj.

Do, kiam ni transiris al la antaŭprova etapo, diversaj problemoj komencis aperi kaj, kvankam en eta maniero, estis necese ŝanĝi la dokumentaron ofte - kvar malsamaj teamoj, ĉiutage, preskaŭ samtempe, kun diskutoj. Ĉiuj ĉi tiuj ŝanĝoj okazis per unu inĝeniero - arkitekto. La projekt-dezajnodosiero estis grandega, kaj kiel rezulto, la arkitekto estis superŝutita de rutina laboro implikanta multe da kopiado, redaktado, faris multajn erarojn, devis duoble kontroli ĉion, resendi ĝin, kaj ĝenerale ĝi estis proksima al kaoso.

En ĉi tiu kazo, ĉi tiu aliro, la aliro labori pri MS Word-dokumento, funkciis tre malfacile kaj kreis problemojn.

Git, Markdown

Fronte al la problemo priskribita en la supra ekzemplo, mi komencis esplori ĉi tiun aferon.
Mi vidis ke la uzo de Markdown kune kun Git kiam oni kreas dokumentojn.

Git estas evoluilo. Sed kial ne uzi ĝin por la dokumenta procezo? En ĉi tiu kazo, la afero de pluruza laboro fariĝas solvita. Sed por plene profiti la kapablojn de Git, ni bezonas tekstdokumentan formaton, ni devas trovi ilon krom MS Word, kaj Markdown estas bonega por ĉi tiuj celoj.

Markdown estas simpla tekstmarklingvo. Ĝi estas desegnita por krei bele desegnitajn tekstojn en regulaj TXT-dosieroj. Se ni kreas niajn dokumentojn en Markdown, tiam la Markdown - Git kombinaĵo aspektas nature.

Kaj ĉio estus en ordo, kaj ĉi-momente ni povus ĉesigi ĝin, se ne pro nia dua kondiĉo: “pro tio, ni bezonas dokumenton en certa formato, kun la atributoj de kompania stilo, kreita laŭ certa ŝablono” (kaj ni konsentis komence, ke por Certe ĝi estos MS Word). Tio estas, se ni decidas uzi Markdown, tiam ni devas iel konverti ĉi tiun dosieron en .docx de la bezonata tipo.

Estas programoj por konverti inter malsamaj formatoj, ekz. pandoc.
Vi povas konverti Markdown dosieron al .docx formato kun ĉi tiu programo.
Sed tamen, vi devas kompreni, ke unue, ne ĉio, kio estas en Markdown, estos konvertita al MS Word kaj, due, MS Word estas tuta lando kompare kun la svelta, sed ankoraŭ urbeto, Markdown. Estas grandega kvanto de ĉio, kio estas en Word, kiu ne estas en ajna formo en Markdown. Vi ne povas simple daŭrigi kaj konverti vian Markdown-formaton en la deziratan MS Word-formaton per iuj Pandoc-klavoj. Do kutime, post konvertiĝo, vi devas "redakti" la rezultan .docx-dokumenton permane, kiu denove povas esti temporaba kaj konduki al eraroj.

Se ni povus verki skripton, kiu aŭtomate "finos" tion, kion Pandoc ne povis pritrakti, tio estus ideala solvo.

Pro la neidenteco de la funkcieco de MS Word kaj Markdown, estas neeble solvi ĉi tiun problemon ĝenerale, mi pensas, sed ĉu tio povas esti farita rilate al specifaj situacioj, specifaj postuloj? Mia sperto montris, ke jes, ĝi eblas kaj plej verŝajne ĝi eblas por multaj, aŭ eble eĉ plej multaj situacioj.

Solvo de aparta problemo

Do, en mia kazo, post konverti la dosieron per Pandoc, mi devis mane fari plian dosieron pritrakti, nome

• aldonu kampojn al Word kun aŭtomata numerado de titoloj (subtitoloj) de tabeloj kaj bildoj
• ŝanĝi tabelan stilon

Mi ne trovis kiel fari tion per normaj (Pandoc) aŭ konataj rimedoj. Do mi aplikis la python-skripton per pywin32 pako. Kiel rezulto, mi ricevis plenan aŭtomatigon. Nun mi povas konverti mian Markdown-dosieron en la deziratan MS Word-dokumentformon per unu komando.

Vidu detalojn tie.

Noto

En ĉi tiu ekzemplo, mi kompreneble konvertas iun abstraktan Markdown-dosieron, sed ĝuste la sama aliro estis aplikita al la "batala" dokumento, kaj la eligo, kiun mi ricevis, estis preskaŭ ekzakte la sama MS Word-dokumento, kiun ni antaŭe ricevis per mana formatado. .

Ĝenerale, kun pywin32 ni ricevas preskaŭ kompletan kontrolon de la MS Word-dokumento, kio permesas al ni ŝanĝi ĝin kaj alporti ĝin al la formo, kiun via kompania normo postulas. Kompreneble, la samaj celoj povus esti atingitaj uzante aliajn ilojn, ekzemple, VBA makroojn, sed estis pli oportune por mi uzi python.

Mallonga formulo por ĉi tiu aliro:

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

Ne gravas kio estas "io". En mia kazo estis Pandoc kaj python kun pywin32. Viaj preferoj povas esti malsamaj, sed la grava afero estas, ke ĝi eblas. Kaj ĉi tiu estas la ĉefa mesaĝo de ĉi tiu artikolo.

Por resumi, la ideo estas, ke kun ĉi tiu aliro vi laboras nur kun la Markdown-dosiero kaj uzas Git por kunlaboro kaj versio-kontrolo, kaj nur kiam necese (ekzemple, por provizi dokumentadon al la kliento) aŭtomate kreas dosieron en la dezirata formato ( ekzemple MS Word ).

procezo

Mi pensas, ke por multaj, la supre donita formulo sufiĉas por kompreni kiel la procezo de laboro kun dokumentado nun povas esti organizita. Sed tamen, mi kutime koncentriĝas pri retaj inĝenieroj, do mi montros ĝenerale kiel la laborprocezo nun povas aspekti, kaj kiel tio diferencas de la aliro de redaktado de MS Word-dosieroj.

Por esti specifa, ni elektos GitHub kiel la platformon por labori kun Git. Tiam vi devus krei deponejon kaj meti la Markdown-dosieron aŭ dosierojn, kun kiuj vi planas labori en la ĉefa branĉo.

Ni rigardos simplan procezon bazitan sur la "github-fluo". Ĝia priskribo troveblas kaj en la interreto kaj sur habre.

Ni diru, ke kvar homoj laboras pri la dokumentado kaj vi estas unu el ili. Tiam kvar pliaj branĉoj estas kreitaj, ekzemple, kun la nomoj de ĉi tiuj homoj. Ĉiu laboras loke, en sia branĉo kaj faras ŝanĝojn kun ĉio necesa git komandoj.

Fininte iun finitan laboron, vi kreas tiran peton, tiel komencante diskuton pri viaj ŝanĝoj. Eble, dum la diskuto, montriĝas, ke vi devus aldoni aŭ ŝanĝi ion alian. En ĉi tiu kazo, vi faras la necesajn ŝanĝojn kaj kreas plian tiran peton. Fine, viaj ŝanĝoj estas akceptitaj kaj kunfanditaj en la majstran branĉon (aŭ forĵetitaj).

Kompreneble, ĉi tio estas sufiĉe ĝenerala priskribo. Por krei detalan procezon, mi sugestas kontakti viajn programistojn aŭ trovi spertajn homojn. Sed mi volas rimarki, ke la baro al eniro en Git estas sufiĉe malalta. Ĉi tio ne signifas, ke la protokolo estas simpla, sed vi povas komenci simple. Se vi tute ne scias ion, mi pensas, ke post kelkaj horoj aŭ eble tagoj lerni kaj instali, vi povas ekuzi ĝin.

Kio estas la avantaĝo de ĉi tiu aliro kompare al, ekzemple, la procezo priskribita en la supra ekzemplo?

Fakte, la procezoj estas sufiĉe similaj, vi ĵus anstataŭigis

kopii dosieron -> krei branĉon
kopii tekston al la fina dosiero -> kunfandi
kopiante la lastajn ŝanĝojn al vi mem -> git pull/fetch
diskuto en korespondado -> tirpetoj
track mode -> git diff
lasta aprobita versio -> majstra branĉo
sekurkopio (kopiante al fora servilo) -> git push
...

Tiel, vi aŭtomatigis ĉion, kion vi jam devis fari, sed permane.

Je pli alta nivelo ĝi permesas vin

• krei klaran, simplan kaj kontrolitan procezon por dokumentoŝanĝoj
• ĉar vi kreas la finan dokumenton (en nia ekzemplo MS Word) aŭtomate, tio reduktas la verŝajnecon de formataj eraroj

Noto

Dirinte tion, mi pensas, ke estas evidente, ke eĉ se vi laboras nur pri dokumentado, uzi Git povas multe plifaciligi vian laboron.

Ĉio ĉi plibonigas la kvaliton de dokumentado kaj reduktas la tempon por ĝia kreado. Kaj alia malgranda gratifiko - vi lernos Git, kiu helpos vin kiam vi aŭtomatigas vian reton :)

Kiel ŝanĝi al nova procezo?

Komence de la artikolo, mi skribis, ke morgaŭ vi povas komenci labori en nova maniero. Kiel preni vian laboron en novan direkton?

Jen la sinsekvo de paŝoj, kiujn vi plej verŝajne devos sekvi:

• se via dokumento estas tre granda, dividu ĝin en partojn
• konverti ĉiun parton al Markdown (uzante Pandoc ekzemple)
• instalu unu el la Markdown-redaktiloj (mi uzas Typora)
• plej verŝajne vi devos ĝustigi la formatadon de la kreitaj Markdown-dokumentoj
• komencu apliki la procezon priskribitan en la antaŭa ĉapitro
• samtempe, komencu modifi la konvertan skripton laŭ via tasko (aŭ kreu ion propran)

Vi ne devas atendi ĝis vi kreis kaj perfektigis la Markdwon-konvertan mekanismon -> la bezonata eligo-tipo de dokumento. La afero estas, ke, eĉ se vi ne kapablas rapide plene aŭtomatigi la proceduron por konverti viajn Markdown-dosierojn, vi ankoraŭ povas fari ĝin en iu formo uzante Pandoc kaj poste alporti ĝin al la fina formo permane. Kutime oni ne bezonas tion fari ofte, sed nur ĉe la fino de certaj etapoj, kaj ĉi tiu manlibro, kvankam maloportuna, estas ankoraŭ, laŭ mi, sufiĉe akceptebla ĉe la sencimiga etapo kaj ne devus "malrapidigi" la procezon. multe.

Ĉio alia (Markdown, Git, Pandoc, Typora) jam estas preta kaj ne postulas multe da penado aŭ tempo por komenci labori kun ili.

fonto: www.habr.com