Parfois, non seulement la documentation elle-même, mais aussi le processus d'élaboration peuvent être critiques. Par exemple, dans le cas de projets, la majeure partie du travail est liée à la préparation de la documentation, et un processus incorrect peut entraîner des erreurs et même une perte d'informations, et, par conséquent, une perte de temps et de profit. Mais même si ce sujet n'est pas au cœur de votre travail et se situe à la périphérie, le processus correct peut tout de même améliorer la qualité du document et vous faire gagner du temps.
L'approche décrite ici, avec
un exemple de mise en œuvre spécifique , a un seuil d'entrée bas. Techniquement, demain, vous pouvez commencer à travailler d'une nouvelle manière.
Énoncé du problème
Vous devez créer un certain document ou un ensemble de documents. Il s'agit peut-être de la documentation du projet ou de la journalisation de votre réseau, ou quelque chose de plus simple, par exemple, vous devriez décrire les processus dans l'entreprise ou dans votre département. En général, nous parlons de tout document ou ensemble de documents contenant du texte, des images, des plaques ... Nous compliquons la tâche par le fait que
- ce travail implique un travail en commun, les efforts d'un groupe ou de plusieurs groupes d'employés
- à la sortie, vous voulez avoir un document dans un certain format, avec des attributs de style d'entreprise, créé selon un modèle spécifique. Pour être précis, nous supposerons qu'il s'agit de MS Word (.docx)
Il y a 10 ans, l'approche était sans ambiguïté: nous créerions un ou plusieurs documents MS Word et organiserions en quelque sorte le travail sur le changement.
Et cette approche est toujours valable. Il est également utilisé par les grands intégrateurs lors de la création de la documentation de projet. Mais il est intuitivement clair que si vous êtes vraiment intensif, avec de nombreuses modifications et discussions, pendant longtemps à travailler sur un document, cette approche n'est pas très pratique.
Exemple
J'ai ressenti ce problème de façon assez aiguë en travaillant dans un grand intégrateur. Le processus de modification de la documentation de conception était le suivant:
- ingénieur télécharge la dernière version du document MS Word (.docx)
- change le nom
- apporte des modifications au mod de piste
- envoie le document avec les corrections à l'architecte
- envoie également une liste de toutes les corrections avec des commentaires
- architecte analyse le changement
- si tout va bien, copie les données de modification dans le fichier avec la dernière version, modifie la version, les place sur une ressource partagée
- s'il y a des commentaires, alors une discussion est lancée (email ou rassemblements)
- un consensus est atteint
- paragraphes 3 à 9
Bien que le travail n'ait pas été intense, il a en quelque sorte, mais a quand même fonctionné. Mais à un certain point, ce processus est devenu le goulot d'étranglement de l'ensemble du projet et a conduit à des problèmes. Le fait est que tout devient mauvais dès que des changements sont effectués souvent et simultanément par plusieurs équipes.
Ainsi, lorsque nous sommes passés à la phase de test préliminaire, divers problèmes ont commencé à apparaître et, bien que dans les détails, nous ayons dû changer souvent la documentation - quatre équipes différentes, quotidiennement, presque simultanément, avec des discussions. Tous ces changements sont passés par un seul ingénieur - un architecte. Le dossier avec la conception du projet était énorme, et en conséquence, l'architecte était submergé par le travail de routine associé à beaucoup de copie, d'édition, a fait beaucoup d'erreurs, j'ai dû revérifier, renvoyer, et en général c'était proche du chaos.
Dans ce cas, cette approche, l'approche consistant à travailler sur un document MS Word, a fonctionné avec un grand grincement et a créé des problèmes.
Git markdown
Face au problème décrit dans l'exemple ci-dessus, j'ai commencé à rechercher ce problème.
J'ai vu que l'utilisation de
Markdown avec
Git lors de la création de documents devient de plus en plus populaire.
Git est un outil de développement. Mais pourquoi ne pas l'utiliser pour le processus de documentation? Dans ce cas, le problème du travail multi-utilisateur est résolu. Mais pour utiliser pleinement les fonctionnalités de Git, nous avons besoin d'un format de texte pour le document, nous devons trouver un autre outil, pas MS Word, et Markdown est idéal à ces fins.
Markdown est un langage de balisage de texte simple. Il est conçu pour créer des textes magnifiquement conçus dans des fichiers TXT standard. Si nous créons nos documents dans Markdown, le lien Markdown-Git semble naturel.
Et tout irait bien, et à cet endroit, il serait possible de mettre un terme si ce n'était de notre deuxième condition: «à la sortie, nous avons besoin d'un document dans un certain format, avec des attributs de style d'entreprise créés selon un certain modèle» (et nous avons d'abord convenu que pour certitude, ce sera MS Word). Autrement dit, si nous décidons d'utiliser Markdown, nous devons en quelque sorte convertir ce fichier en .docx du type requis.
Il existe des programmes de conversion entre différents formats, par exemple
Pandoc .
Vous pouvez convertir le fichier Markdown au format .docx avec ce programme.
Mais encore, vous devez comprendre que, premièrement, tout ce qui se trouve dans Markdown ne sera pas converti en MS Word et, deuxièmement, MS Word est un pays entier par rapport à la ville mince, mais toujours petite, Markdown. Il y a une énorme quantité de tout ce qui est dans Word et sous aucune forme dans Markdown. Vous ne pouvez pas simplement prendre votre format Markdown avec les clés Pandoc souhaitées dans la forme souhaitée de MS Word. Donc, généralement, après la conversion, vous devez «affiner» le document .docx reçu manuellement, ce qui peut encore une fois prendre du temps et entraîner des erreurs.
Si nous pouvions écrire un script qui «terminerait» automatiquement ce que Pandoc ne pourrait pas faire, ce serait une solution idéale.
Étant donné que MS Word et la fonctionnalité Markdown ne sont pas identiques en termes généraux, il est impossible de résoudre ce problème, je pense, mais cela peut-il être fait en relation avec des situations spécifiques, des exigences spécifiques? Mon expérience a montré que oui, c'est possible et très probablement pour de nombreuses, voire la plupart des situations.
Solution d'un problème particulier
Donc, dans mon cas, après avoir converti le fichier en utilisant Pandoc, j'ai dû faire manuellement un traitement de fichier supplémentaire, à savoir
- ajouter des champs dans Word avec numérotation automatique des légendes des tableaux et des images
- changer le style des tableaux
Je n'ai pas trouvé comment le faire en utilisant des moyens standard (Pandoc) ou connus. Par conséquent, j'ai appliqué un script python avec le package
pywin32 . En conséquence, j'ai obtenu une automatisation complète. Maintenant, je peux convertir mon fichier Markdown sous la forme souhaitée de document MS Word avec une seule commande.
Voir les détails
ici .
Remarque
Dans cet exemple, je vais bien sûr convertir un fichier Markdown abstrait, mais exactement la même approche a été appliquée au document «combat», et à la sortie, j'ai reçu presque exactement le même document MS Word, que nous avions précédemment reçu par formatage manuel.
En général, avec pywin32, nous obtenons un contrôle presque complet sur le document MS Word, ce qui nous permet de le modifier et de lui donner l'apparence requise par votre norme d'entreprise. Bien sûr, les mêmes objectifs pouvaient être atteints en utilisant d'autres outils, par exemple les macros VBA, mais c'était plus pratique pour moi d'utiliser python.
Une formule brève pour cette approche:
Markdown + Git -- () --> MS Word
Ce n'est pas si important ce qu'est «quelque chose». Dans mon cas, c'était Pandoc et python avec pywin32. Vous pouvez avoir des préférences différentes, mais l'important est que cela soit possible. Et c'est le principal message de cet article.
En résumé, l'idée est qu'avec cette approche, vous ne travaillez qu'avec le fichier Markdown et utilisez Git pour organiser la collaboration et le contrôle de version, et seulement si nécessaire (par exemple, pour fournir de la documentation au client) créez automatiquement le fichier du format souhaité (par exemple, MS Word )
Le processus
Je pense que pour beaucoup, la formule donnée ci-dessus suffit pour comprendre comment le processus de travail avec la documentation peut être organisé maintenant. Mais néanmoins, je me concentre généralement sur les ingénieurs réseau, donc je vais décrire en général à quoi le processus peut maintenant ressembler et en quoi il diffère de l'approche de modification des fichiers MS Word.
Pour être précis, nous choisirons GitHub comme plate-forme pour travailler avec Git. Ensuite, vous devez créer un référentiel et placer le ou les fichiers Markdown avec lesquels vous prévoyez de travailler dans la branche principale.
Nous examinerons un processus simple basé sur le flux github. Sa description peut être trouvée à la fois sur Internet et sur le
Habr .
Supposons que quatre personnes travaillent sur la documentation et que vous en faites partie. Ensuite, quatre branches supplémentaires sont créées, par exemple, avec les noms de ces personnes. Chacun fonctionne localement, dans sa propre branche et apporte des modifications avec toutes les
commandes git nécessaires.
Une fois le travail terminé, vous formulez une demande d'extraction, amorçant ainsi une discussion sur vos modifications. Au cours du processus de discussion, il se peut que vous deviez ajouter ou modifier autre chose. Dans ce cas, vous apportez les modifications nécessaires et créez une demande d'extraction supplémentaire. Au final, vos modifications sont acceptées et fusionnées avec la branche principale (ou rejetées).
Bien sûr, c'est une description assez générale. Je suggère de contacter vos développeurs ou de trouver des personnes compétentes pour créer un processus détaillé. Mais je tiens à noter que le seuil d'entrée dans Git est assez bas. Cela ne signifie pas que le protocole est simple, mais vous pouvez commencer par un protocole simple. Si vous ne savez rien du tout, je pense, après avoir passé plusieurs heures ou peut-être des jours à étudier et à installer, vous pouvez commencer à l'utiliser.
Quelle est l'utilité de cette approche en comparaison, par exemple, avec le processus décrit dans l'exemple ci-dessus?
En fait, les processus sont assez similaires, vous venez de remplacer
copier un fichier -> créer une branche
copier le texte dans le fichier final-> fusionner (fusionner)
copier les dernières modifications pour vous -> git pull / fetch
discussion en correspondance -> demandes de tirage
mode piste -> git diff
dernière version approuvée -> branche principale
sauvegarde (copie sur un serveur distant) -> git push
...
Ainsi, vous avez automatisé tout ce que vous aviez déjà à faire, mais manuellement.
À un niveau supérieur, cela vous permet
- Créez un processus clair, simple et contrôlé pour modifier la documentation.
- parce que le document final (dans notre exemple MS Word) que vous créez automatiquement, cela réduit la probabilité d'erreurs liées au formatage
Remarque
Au vu de ce qui précède, je pense qu'il est évident que même si vous travaillez uniquement sur la documentation, l'utilisation de Git peut grandement faciliter votre travail
Tout cela améliore la qualité de la documentation et réduit le temps de sa création. Et un petit bonus - vous apprenez Git, qui vous aidera à automatiser votre réseau :)
Comment passer à un nouveau processus?
Au début de l'article, j'ai écrit que demain, vous pouvez commencer à travailler d'une nouvelle manière. Comment traduire votre travail dans une nouvelle direction?
Voici la séquence d'étapes que vous devrez probablement effectuer:
- si votre document est très volumineux, divisez-le en morceaux
- convertir chaque partie en Markdown (en utilisant Pandoc, par exemple)
- installer l'un des éditeurs Markdown (j'utilise Typora )
- vous devrez probablement modifier la mise en forme des documents Markdown créés
- commencer à appliquer le processus décrit dans le chapitre précédent
- parallèle, commencez à modifier le script de conversion pour l'adapter à votre tâche (ou créez quelque chose de votre choix)
Vous n'avez pas à attendre de créer et de déboguer parfaitement le mécanisme de conversion Markdwon -> requis pour le type de document de sortie. Le fait est que même si vous ne pouvez pas rapidement rapidement automatiser complètement la conversion de vos fichiers Markdown, vous pouvez toujours le faire sous n'importe quelle forme en utilisant Pandoc, puis le ramener manuellement à sa forme finale. Habituellement, vous n'avez pas besoin de le faire souvent, mais seulement à la fin de certaines étapes, et ce travail manuel, bien que peu pratique, est toujours, à mon avis, tout à fait acceptable au stade du débogage et ne devrait pas ralentir beaucoup le processus.
Tout le reste (Markdown, Git, Pandoc, Typora) est prêt et ne nécessite pas d'efforts ou de temps particuliers pour commencer à travailler avec eux.