Utilitzeu GIT quan documenteu

De vegades, no només la documentació en si, sinó també el procés de treball-hi pot ser crític. Per exemple, en el cas dels projectes, la part del lleó del treball està relacionada amb l'elaboració de la documentació, i un procés incorrecte pot comportar errors i fins i tot pèrdua d'informació i, en conseqüència, pèrdua de temps i beneficis. Però fins i tot si aquest tema no és central per al vostre treball i està a la perifèria, el procés correcte encara pot millorar la qualitat del document i estalviar-vos temps.

L'enfocament descrit aquí, amb exemple d'una implementació concreta, té una barrera d'entrada baixa. Tècnicament, demà podeu començar a treballar d'una manera nova.

Declaració de problemes

Heu de crear un document o conjunt de documents. Potser es tracta de documentació del projecte o registre de la vostra xarxa, o alguna cosa més senzilla, per exemple, heu de descriure els processos a l'empresa o al vostre departament. En general, estem parlant de qualsevol document o conjunt de documents amb text, imatges, rètols... Complicarem la tasca pel fet que

1. aquest treball implica el treball conjunt, l'esforç d'un grup o de diversos grups d'empleats
2. Com a resultat, voleu tenir un document en un format determinat, amb atributs d'estil corporatiu, creat segons una plantilla determinada. Per ser específics, suposarem que es tracta de MS Word (.docx)

Fa 10 anys l'enfocament hauria estat senzill: hauríem creat un document o documents de MS Word i, d'alguna manera, hauríem organitzat el treball de canvi.

I aquest plantejament encara és vigent. També l'utilitzen grans integradors quan creen la documentació del projecte. Però és intuïtivament clar que si realment treballes intensament en un document, amb moltes modificacions i discussions, durant un llarg període de temps, aquest enfocament no és gaire convenient.

Exemple

Vaig sentir aquest problema amb força mentre treballava per a un gran integrador. El procés de canvi de la documentació de disseny va ser el següent:

1. L'enginyer baixa la darrera versió del document MS Word (.docx).
2. canvia de nom
3. fa canvis per fer un seguiment de la moda
4. envia el document amb les edicions a l'arquitecte
5. també envia una llista de totes les correccions amb comentaris
6. l'arquitecte analitza els canvis
7. si tot va bé, copia aquests canvis en un fitxer amb la darrera versió, canvia la versió i la puja a un recurs compartit
8. si hi ha comentaris, s'inicia una discussió (correu electrònic o reunions)
9. s'arriba a un consens
10. altres punts 3 - 9

Tot i que la feina no va ser intensa, d'alguna manera ho va ser, però tot i així va funcionar. Però en un moment determinat, aquest procés es va convertir en el coll d'ampolla de tot el projecte i va provocar problemes. La qüestió és que les coses es posen malament tan bon punt es fan canvis amb freqüència i simultàniament per diversos equips.

Així, quan vam passar a l'etapa de proves preliminars, van començar a aparèixer diversos problemes i, encara que de manera petita, va ser necessari canviar la documentació sovint: quatre equips diferents, cada dia, gairebé simultàniament, amb discussions. Tots aquests canvis van tenir lloc a través d'un enginyer: un arquitecte. El fitxer de disseny del projecte era enorme i, com a resultat, l'arquitecte es va veure aclaparat amb un treball rutinari que implicava moltes còpies, edició, va cometre molts errors, va haver de comprovar-ho tot, tornar-lo a enviar i, en general, estava a prop de Chaos.

En aquest cas, aquest enfocament, el plantejament de treballar en un document MS Word, va funcionar amb molta dificultat i va crear problemes.

Git, Markdown

Davant del problema descrit a l'exemple anterior, vaig començar a investigar aquest tema.
Vaig veure que l'ús de Markdown juntament amb anar en crear documents.

Git és una eina de desenvolupament. Però, per què no utilitzar-lo per al procés de documentació? En aquest cas, es resol el problema del treball multiusuari. Però per aprofitar al màxim les capacitats de Git, necessitem un format de document de text, hem de trobar una eina diferent de MS Word i Markdown és fantàstic per a aquests propòsits.

Markdown és un llenguatge de marcat de text senzill. Està dissenyat per crear textos ben dissenyats en fitxers TXT normals. Si creem els nostres documents a Markdown, la combinació Markdown - Git sembla natural.

I tot aniria bé, i en aquest punt podríem posar fi, si no fos per la nostra segona condició: “en conseqüència, necessitem un document en un format determinat, amb els atributs d'un estil corporatiu, creat segons una plantilla determinada” (i vam acordar al principi que per Certament serà MS Word). És a dir, si decidim utilitzar Markdown, hem de convertir d'alguna manera aquest fitxer en un .docx del tipus requerit.

Hi ha programes per convertir entre diferents formats, p. Pandoc.
Podeu convertir el fitxer Markdown a format .docx amb aquest programa.
Però tot i així, cal entendre que, en primer lloc, no tot el que hi ha a Markdown es convertirà a MS Word i, en segon lloc, MS Word és un país sencer en comparació amb l'esvelt, però encara petit poble, Markdown. Hi ha una gran quantitat de tot el que hi ha a Word que no té cap forma a Markdown. No podeu seguir endavant i convertir el vostre format Markdown al format MS Word desitjat mitjançant determinades tecles Pandoc. Per tant, normalment, després de la conversió, heu d'"editar" el document .docx resultant manualment, cosa que de nou pot consumir molt de temps i provocar errors.

Si poguéssim escriure un script que "acabaria" automàticament allò que Pandoc no podia gestionar, seria una solució ideal.

A causa de la no identitat de la funcionalitat de MS Word i Markdown, és impossible resoldre aquest problema en general, crec, però es pot fer en relació a situacions concretes, requisits específics? La meva experiència m'ha demostrat que sí, és possible i molt probablement és possible per a moltes, o potser fins i tot per a la majoria de situacions.

Solució d'un problema concret

Per tant, en el meu cas, després de convertir el fitxer amb Pandoc, vaig haver de fer manualment un processament addicional del fitxer, és a dir

• afegir camps a Word amb numeració automàtica d'encapçalaments (títols) de taules i imatges
• canviar l'estil de la taula

No he trobat com fer-ho amb mitjans estàndard (Pandoc) o coneguts. Així que vaig aplicar l'script Python amb pywin32 paquet. Com a resultat, vaig obtenir una automatització completa. Ara puc convertir el meu fitxer Markdown al formulari de document MS Word desitjat amb una ordre.

Veure detalls aquí.

Nota:

En aquest exemple, per descomptat, convertí algun fitxer de Markdown abstracte, però es va aplicar exactament el mateix enfocament al document de "combat", i la sortida que vaig rebre era gairebé exactament el mateix document de MS Word que havíem rebut prèviament mitjançant el format manual. .

En general, amb pywin32 aconseguim un control gairebé complet sobre el document MS Word, la qual cosa ens permet canviar-lo i portar-lo a la forma que requereixi el vostre estàndard corporatiu. Per descomptat, els mateixos objectius es podrien aconseguir amb altres eines, per exemple, macros VBA, però em va ser més convenient utilitzar Python.

Una fórmula breu per a aquest enfocament:

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

No importa què sigui "alguna cosa". En el meu cas era Pandoc i python amb pywin32. Les teves preferències poden ser diferents, però l'important és que sigui possible. I aquest és el missatge principal d'aquest article.

En resum, la idea és que amb aquest enfocament només treballeu amb el fitxer Markdown i utilitzeu Git per a la col·laboració i el control de versions, i només quan sigui necessari (per exemple, per proporcionar documentació al client) creeu automàticament un fitxer en el format desitjat ( per exemple, MS Word).

procés

Crec que per a molts, la fórmula donada anteriorment és suficient per entendre com ara es pot organitzar el procés de treball amb documentació. Tot i així, acostumo a centrar-me en els enginyers de xarxa, així que mostraré en termes generals com pot semblar ara el procés de treball i com es diferencia de l'enfocament d'edició de fitxers MS Word.

Per ser específics, triarem GitHub com a plataforma per treballar amb Git. Aleshores, hauríeu de crear un dipòsit i col·locar el fitxer Markdown o els fitxers amb els quals voleu treballar a la branca mestra.

Veurem un procés senzill basat en el "flux github". La seva descripció es pot trobar tant a Internet com a habre.

Suposem que hi ha quatre persones treballant en la documentació i tu en ets una. Aleshores es creen quatre branques addicionals, per exemple, amb els noms d'aquestes persones. Cadascú treballa de manera local, a la seva branca i fa canvis amb tot el necessari ordres git.

Després d'haver completat algun treball completat, creeu una sol·licitud d'extracció, iniciant així una discussió sobre els vostres canvis. Potser, durant la discussió, resulta que hauríeu d'afegir o canviar alguna cosa més. En aquest cas, feu els canvis necessaris i creeu una sol·licitud d'extracció addicional. Finalment, els vostres canvis s'accepten i es fusionen a la branca mestra (o es descarten).

Per descomptat, aquesta és una descripció força general. Per crear un procés detallat, us suggereixo contactar amb els vostres desenvolupadors o trobar gent experta. Però vull assenyalar que la barrera per entrar a Git és bastant baixa. Això no vol dir que el protocol sigui senzill, però podeu començar senzill. Si no saps res, crec que després de passar unes hores o potser dies aprenent i instal·lant, pots començar a utilitzar-lo.

Quin és el benefici d'aquest enfocament en comparació, per exemple, amb el procés descrit a l'exemple anterior?

De fet, els processos són força semblants, acabes de substituir

copiant un fitxer -> creant una branca
copiant el text al fitxer final -> fusionant
copiant els darrers canvis a tu mateix -> git pull/fetch
discussió en correspondència -> pull requests
mode de seguiment -> git diff
darrera versió aprovada -> branca mestra
còpia de seguretat (copiant a un servidor remot) -> git push
...

Així, vas automatitzar tot el que ja havies de fer, però manualment.

A un nivell superior t'ho permet

• crear un procés clar, senzill i controlat per als canvis de documents
• perquè creeu el document final (en el nostre exemple MS Word) automàticament, això redueix la probabilitat d'errors de format

Nota:

Dit això, crec que és obvi que, fins i tot si esteu treballant només amb documentació, utilitzar Git us pot facilitar molt la feina.

Tot això millora la qualitat de la documentació i redueix el temps per a la seva creació. I un altre petit avantatge: aprendràs Git, que t'ajudarà a automatitzar la teva xarxa :)

Com canviar a un procés nou?

Al principi de l'article, vaig escriure que demà pots començar a treballar d'una manera nova. Com portar el teu treball en una nova direcció?

Aquí teniu la seqüència de passos que probablement haureu de seguir:

• si el vostre document és molt gran, dividiu-lo en parts
• convertir cada part a Markdown (utilitzant Pandoc, per exemple)
• instal·leu un dels editors de Markdown (jo faig servir Typora)
• molt probablement haureu d'ajustar el format dels documents de Markdown creats
• començar a aplicar el procés descrit al capítol anterior
• al mateix temps, comenceu a modificar l'script de conversió perquè s'adapti a la vostra tasca (o creeu alguna cosa pròpia)

No cal que espereu fins que hàgiu creat i perfeccionat el mecanisme de conversió de Markdwon -> el tipus de document de sortida necessari. La qüestió és que, encara que no pugueu automatitzar completament ràpidament el procediment per convertir els vostres fitxers Markdown, encara podeu fer-ho d'alguna manera mitjançant Pandoc i després portar-lo al formulari final manualment. Normalment no cal fer-ho sovint, sinó només al final de determinades etapes, i aquest treball manual, tot i que és incòmode, segueix sent, al meu entendre, bastant acceptable a l'etapa de depuració i no hauria de "ralentir" el procés. molt.

Tota la resta (Markdown, Git, Pandoc, Typora) ja està llesta i no requereix gaire esforç ni temps per començar a treballar-hi.

Font: www.habr.com