Utilisez GIT pour documenter

Parfois, non seulement la documentation elle-même, mais aussi le processus de son élaboration peut être critique. Par exemple, dans le cas de projets, une grande partie du travail est liée à la préparation de la documentation, et un processus incorrect peut mener à des erreurs et même à la perte d'informations, ce qui entraîne une perte de temps et de bénéfices. Mais même si ce thème n'est pas central dans votre travail et se situe à la périphérie, un bon processus peut améliorer la qualité du document et vous faire gagner du temps.

L'approche présentée ici, avec un exemple de mise en œuvre concrète, a une faible barrière d'entrée. Techniquement, vous pouvez commencer à travailler différemment dès demain.

Définition du problème

Vous devez créer un document ou un ensemble de documents. Cela pourrait être de la documentation de projet ou un protocole de votre réseau, ou quelque chose de plus simple, par exemple, vous devez décrire les processus dans votre entreprise ou dans votre département. En gros, il s'agit de tout document ou ensemble de documents contenant du texte, des images, des tableaux… Compliquons les choses en disant que

1. ce travail implique un effort collaboratif, des efforts de groupes ou de plusieurs équipes d'employés
2. et à la fin, vous souhaitez avoir un document dans un format spécifique, avec des attributs de style d'entreprise, créé selon un modèle précis. Pour plus de clarté, considérons qu'il s'agit d'un document MS Word (.docx).

Il y a 10 ans, l'approche aurait été claire : nous aurions créé un document ou des documents MS Word et organisé d'une manière ou d'une autre le travail de modification.

Et cette approche est toujours valable. Elle est utilisée notamment par de grands intégrateurs lors de la création de documentation de projet. Mais il est intuitivement évident que, si vous travaillez intensivement sur un document avec de nombreuses modifications et discussions pendant une longue période, cette approche n'est pas très pratique.

Exemple

J'ai ressenti cette problématique de manière assez aiguë en travaillant dans un grand intégrateur. Le processus de modification de la documentation de projet était le suivant :

1. l'ingénieur télécharge la dernière version du document MS Word (.docx)
2. change le nom
3. apporte des modifications en mode suivi
4. envoie le document avec les modifications à l'architecte
5. envoie également la liste de toutes les corrections avec des commentaires
6. l'architecte analyse les changements
7. si tout va bien, il copie les données de modification dans le fichier avec la dernière version, change la version et le publie sur la ressource commune
8. s'il y a des remarques, une discussion est initiée (email ou réunions)
9. un consensus est atteint
10. ensuite les points 3 à 9

Tant que le travail n'était pas intensif, ça fonctionnait tant bien que mal. Mais à un certain moment, ce processus est devenu le goulot d'étranglement de l'ensemble du projet et a entraîné des problèmes. Le fait est que tout se complique dès que les modifications sont apportées fréquemment et simultanément par plusieurs équipes.

Ainsi, lorsque nous sommes passés à la phase de test préliminaire, différents problèmes ont commencé à apparaître et, bien que mineurs, la documentation devait être modifiée fréquemment — quatre équipes différentes, quotidiennement, presque en même temps, avec des discussions. Tous ces changements passaient par un seul ingénieur — l'architecte. Le fichier de conception du projet était immense, et par conséquent, l'architecte était submergé par des tâches routinières, impliquant beaucoup de copier-coller, entraînant de nombreuses erreurs, nécessitant des vérifications constantes et des renvois, et en gros, c'était proche du chaos.

Dans ce cas, cette approche, l'approche de travail sur un document MS Word, fonctionnait avec beaucoup de frictions et créait des problèmes.

Git, Markdown

Confronter le problème décrit dans l'exemple ci-dessus m'a poussé à explorer cette question.
J'ai constaté que l'utilisation de Markdown de plus en plus populaire en Git créant des documents.

Git est un outil de développement. Mais pourquoi ne pas l'utiliser pour le processus de documentation ? Dans ce cas, la question du travail collaboratif est résolue. Mais pour tirer pleinement parti des capacités de Git, nous avons besoin d'un format de document textuel, nous devons trouver un autre outil, autre que MS Word, et pour cela, Markdown convient parfaitement.

Markdown est un langage de balisage textuel simple. Il est conçu pour créer des textes bien formatés dans des fichiers au format TXT. Si nous créons nos documents en Markdown, l'association Markdown - Git semble naturelle.

Tout serait bien, et à ce stade, on pourrait mettre un point final, si ce n'était pas pour notre deuxième condition : « nous avons besoin d'un document dans un format spécifique, avec des attributs de style corporate, créé selon un modèle » (et nous avons convenu au départ que pour des raisons de clarté, il s'agira de MS Word). Donc, si nous avons décidé d'utiliser Markdown, nous devons d'une manière ou d'une autre convertir ce fichier en .docx du format requis.

Il existe des programmes de conversion entre différents formats, par exemple, Pandoc.
Vous pouvez convertir un fichier Markdown en format .docx avec ce programme.
Mais il faut comprendre que, d'une part, tout ce qui existe dans Markdown ne sera pas converti en MS Word et que, d'autre part, MS Word est un véritable pays comparé à la ville élégante mais petite qu'est Markdown. Il y a une énorme quantité de fonctionnalités dans Word qui n'existe sous aucune forme dans Markdown. Vous ne pouvez pas simplement prendre et convertir votre format Markdown en un format MS Word souhaité avec certaines clés Pandoc. Donc, généralement, après la conversion, il faut « peaufiner » le document .docx obtenu manuellement, ce qui peut encore une fois être coûteux en termes de temps et conduire à des erreurs.

S'il était possible d'écrire un script qui terminerait automatiquement ce que Pandoc n'a pas pu faire, ce serait une solution idéale.

En raison de la non-identité des fonctionnalités de MS Word et de Markdown de manière générale, je pense qu'il est impossible de résoudre cette tâche, mais peut-on le faire en fonction de situations spécifiques, de besoins concrets ? Mon expérience a montré que oui, c'est possible et probablement réalisable pour de nombreuses, voire la plupart des situations.

Solution d'une tâche particulière

Dans mon cas, après avoir converti le fichier à l'aide de Pandoc, j'ai dû traiter manuellement les fichiers, à savoir

• ajouter dans Word des champs avec numérotation automatique des titres (caption) des tableaux et des images
• modifier le style des tableaux

Je n'ai pas trouvé comment faire cela avec des moyens standard (Pandoc) ou connus. C'est pourquoi j'ai utilisé un script Python avec pywin32 package. En conséquence, j'ai obtenu une automatisation complète. Maintenant, je peux convertir mon fichier Markdown en la forme nécessaire d'un document MS Word avec une seule commande.

Voir les détails ici.

Remarque

Dans cet exemple, je vais bien sûr transformer un fichier Markdown abstrait, mais la même approche a été appliquée à un document « opérationnel », et à la fin, j'ai obtenu pratiquement exactement le même document MS Word que nous obtenions auparavant par formatage manuel.

En résumé, avec pywin32, nous avons pratiquement un contrôle total sur le document MS Word, ce qui nous permet de le modifier et de le mettre en forme selon les exigences de votre norme d'entreprise. Bien sûr, ces mêmes objectifs pourraient être atteints en utilisant d'autres outils, comme des macros VBA, mais j'ai trouvé plus pratique d'utiliser Python.

La formule concise de cette approche :

Markdown + Git -- (quelque chose) --> MS Word

Peu importe ce qu'est « quelque chose ». Dans mon cas, c'était Pandoc et Python avec pywin32. Vous pourriez avoir d'autres préférences, mais l'important est que c'est possible. C'est le message principal de cet article.

En résumé, l'idée est qu'avec cette approche, vous ne travaillez qu'avec un fichier Markdown et utilisez Git pour organiser le travail collaboratif et le contrôle des versions, et seulement lorsque c'est nécessaire (par exemple, pour fournir de la documentation au client), vous créez automatiquement le fichier au format requis (par exemple, MS Word).

Processus

Je pense que pour beaucoup, la formule donnée ci-dessus est suffisante pour comprendre comment le processus de travail avec la documentation peut maintenant être organisé. Mais, comme je m'oriente généralement vers les ingénieurs réseau, je vais montrer brièvement comment le processus peut maintenant fonctionner et comment cela diffère de l'approche d'édition de fichiers MS Word.

Pour être précis, choisissons GitHub comme plateforme de travail avec Git. Vous devez alors créer un dépôt et placer le fichier ou les fichiers Markdown avec lesquels vous prévoyez de travailler dans la branche master.

Nous examinerons un processus simple basé sur le « github flow ». Sa description est disponible à la fois sur Internet et sur Habr.

Supposons que quatre personnes travaillent sur la documentation et que vous en faites partie. Quatre branches supplémentaires sont alors créées, avec par exemple les noms de ces personnes. Chacun travaille localement, dans sa propre branche, et effectue les modifications avec toutes les commandes git nécessaires..

En terminant une tâche, vous créez une pull request, initiant ainsi une discussion sur vos modifications. Il est possible qu'au cours de cette discussion, il apparaisse que vous devez ajouter ou changer quelque chose. Dans ce cas, vous apportez les modifications nécessaires et créez une pull request supplémentaire. En fin de compte, vos modifications sont acceptées et fusionnées (merge) avec la branche master (ou rejetées).

Bien sûr, c'est une description assez générale. Je vous conseille de consulter vos développeurs ou des personnes compétentes pour établir un processus détaillé. Mais je tiens à souligner que le seuil d'entrée pour Git est assez bas. Cela ne signifie pas que le protocole est simple, mais vous pouvez commencer par quelque chose de basique. Si vous n'y connaissez rien, je pense qu'après avoir passé quelques heures ou peut-être quelques jours à étudier et à installer, vous pouvez commencer à l'utiliser.

Quel est donc l'avantage de cette approche par rapport, par exemple, au processus décrit dans l'exemple précédent ?

En réalité, les processus sont assez similaires, vous avez simplement remplacé

copier un fichier -> créer une branche (branch)
copier le texte dans le fichier final -> fusionner (merge)
copier les dernières modifications vers vous -> git pull/fetch
discuter par message -> pull requests
mode de suivi -> git diff
dernière version approuvée -> branche master
sauvegarde (copie sur serveur distant) -> git push
…

Ainsi, vous avez automatisé tout ce que vous deviez déjà faire manuellement.

À un niveau plus élevé, cela vous permet de

• créer un processus clair, simple et contrôlé pour les modifications de la documentation
• comme vous créez automatiquement le document final (dans notre exemple MS Word), cela réduit la probabilité d'erreurs liées à la mise en forme.

Remarque

Pour les raisons évoquées ci-dessus, il est évident que même si vous travaillez seul sur la documentation, l'utilisation de Git peut considérablement simplifier votre travail.

Tout cela améliore la qualité de la documentation et réduit le temps de création. Un petit bonus supplémentaire — vous apprendrez Git, ce qui vous aidera à automatiser votre réseau 🙂

Comment passer à un nouveau processus ?

Au début de cet article, j'ai mentionné qu'à partir de demain, vous pourriez commencer à travailler différemment. Comment transférer votre travail vers une nouvelle approche ?

Voici la séquence d'étapes que vous devrez probablement suivre :

• si votre document est très volumineux, divisez-le en parties.
• convertissez chaque partie en Markdown (par exemple avec Pandoc)
• installez l'un des éditeurs Markdown (j'utilise Typora))
• vous devrez probablement ajuster le formatage des documents Markdown créés
• commencez à appliquer le processus décrit dans le chapitre précédent
• parallèlement, commencez à modifier le script de conversion pour votre tâche (ou créez quelque chose de nouveau)

Vous n'avez pas besoin d'attendre d'avoir créé et débogué parfaitement le mécanisme de conversion Markdown -> le format de document requis. En fait, même si vous n'arrivez pas à automatiser rapidement entièrement la procédure de conversion de vos fichiers Markdown, vous pourrez quand même le faire d'une manière ou d'une autre avec Pandoc et ensuite le peaufiner manuellement. En général, vous n'avez pas besoin de le faire souvent, seulement à la fin de certaines étapes, et ce travail manuel, bien que gênant, est tout de même, à mon avis, tout à fait acceptable au stade de débogage et ne devrait pas trop « freiner » le processus.

Tout le reste (Markdown, Git, Pandoc, Typora) est déjà prêt et ne nécessite pas d'efforts ou de temps particuliers pour commencer à travailler avec.

Source : habr.com