{"id":35419,"date":"2019-10-31T22:04:14","date_gmt":"2019-10-31T19:04:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/ispolzujte-git-pri-dokumentirovanii\/"},"modified":"2019-10-31T22:04:14","modified_gmt":"2019-10-31T19:04:14","slug":"ispolzujte-git-pri-dokumentirovanii","status":"publish","type":"post","link":"https:\/\/prohoster.info\/fr\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Utilisez GIT pour documenter","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Parfois, non seulement la documentation elle-m\u00eame, mais aussi le processus de son \u00e9laboration peut \u00eatre critique. Par exemple, dans le cas de projets, une grande partie du travail est li\u00e9e \u00e0 la pr\u00e9paration de la documentation, et un processus incorrect peut mener \u00e0 des erreurs et m\u00eame \u00e0 la perte d'informations, ce qui entra\u00eene une perte de temps et de b\u00e9n\u00e9fices. Mais m\u00eame si ce th\u00e8me n'est pas central dans votre travail et se situe \u00e0 la p\u00e9riph\u00e9rie, un bon processus peut am\u00e9liorer la qualit\u00e9 du document et vous faire gagner du temps.<\/p>\n

L'approche pr\u00e9sent\u00e9e ici, avec un exemple de mise en \u0153uvre concr\u00e8te<\/a><\/noindex>, a une faible barri\u00e8re d'entr\u00e9e. Techniquement, vous pouvez commencer \u00e0 travailler diff\u00e9remment d\u00e8s demain.
\n<\/a><\/noindex><\/p>\n

D\u00e9finition du probl\u00e8me<\/h3>\n

\nVous devez cr\u00e9er un document ou un ensemble de documents. Cela pourrait \u00eatre de la documentation de projet ou un protocole de votre r\u00e9seau, ou quelque chose de plus simple, par exemple, vous devez d\u00e9crire les processus dans votre entreprise ou dans votre d\u00e9partement. En gros, il s'agit de tout document ou ensemble de documents contenant du texte, des images, des tableaux\u2026 Compliquons les choses en disant que <\/p>\n

    \n
  1. ce travail implique un effort collaboratif, des efforts de groupes ou de plusieurs \u00e9quipes d'employ\u00e9s<\/li>\n
  2. et \u00e0 la fin, vous souhaitez avoir un document dans un format sp\u00e9cifique, avec des attributs de style d'entreprise, cr\u00e9\u00e9 selon un mod\u00e8le pr\u00e9cis. Pour plus de clart\u00e9, consid\u00e9rons qu'il s'agit d'un document MS Word (.docx).<\/li>\n<\/ol>\n

    \nIl y a 10 ans, l'approche aurait \u00e9t\u00e9 claire : nous aurions cr\u00e9\u00e9 un document ou des documents MS Word et organis\u00e9 d'une mani\u00e8re ou d'une autre le travail de modification. <\/p>\n

    Et cette approche est toujours valable. Elle est utilis\u00e9e notamment par de grands int\u00e9grateurs lors de la cr\u00e9ation de documentation de projet. Mais il est intuitivement \u00e9vident que, si vous travaillez intensivement sur un document avec de nombreuses modifications et discussions pendant une longue p\u00e9riode, cette approche n'est pas tr\u00e8s pratique.<\/p>\n

    Exemple<\/b><\/p>\n

    J'ai ressenti cette probl\u00e9matique de mani\u00e8re assez aigu\u00eb en travaillant dans un grand int\u00e9grateur. Le processus de modification de la documentation de projet \u00e9tait le suivant :<\/p>\n

      \n
    1. l'ing\u00e9nieur t\u00e9l\u00e9charge la derni\u00e8re version du document MS Word (.docx)<\/li>\n
    2. change le nom<\/li>\n
    3. apporte des modifications en mode suivi<\/li>\n
    4. envoie le document avec les modifications \u00e0 l'architecte<\/li>\n
    5. envoie \u00e9galement la liste de toutes les corrections avec des commentaires<\/li>\n
    6. l'architecte analyse les changements<\/li>\n
    7. si tout va bien, il copie les donn\u00e9es de modification dans le fichier avec la derni\u00e8re version, change la version et le publie sur la ressource commune<\/li>\n
    8. s'il y a des remarques, une discussion est initi\u00e9e (email ou r\u00e9unions)<\/li>\n
    9. un consensus est atteint<\/li>\n
    10. ensuite les points 3 \u00e0 9<\/li>\n<\/ol>\n

      \nTant que le travail n'\u00e9tait pas intensif, \u00e7a fonctionnait tant bien que mal. Mais \u00e0 un certain moment, ce processus est devenu le goulot d'\u00e9tranglement de l'ensemble du projet et a entra\u00een\u00e9 des probl\u00e8mes. Le fait est que tout se complique d\u00e8s que les modifications sont apport\u00e9es fr\u00e9quemment et simultan\u00e9ment par plusieurs \u00e9quipes.<\/p>\n

      Ainsi, lorsque nous sommes pass\u00e9s \u00e0 la phase de test pr\u00e9liminaire, diff\u00e9rents probl\u00e8mes ont commenc\u00e9 \u00e0 appara\u00eetre et, bien que mineurs, la documentation devait \u00eatre modifi\u00e9e fr\u00e9quemment \u2014 quatre \u00e9quipes diff\u00e9rentes, quotidiennement, presque en m\u00eame temps, avec des discussions. Tous ces changements passaient par un seul ing\u00e9nieur \u2014 l'architecte. Le fichier de conception du projet \u00e9tait immense, et par cons\u00e9quent, l'architecte \u00e9tait submerg\u00e9 par des t\u00e2ches routini\u00e8res, impliquant beaucoup de copier-coller, entra\u00eenant de nombreuses erreurs, n\u00e9cessitant des v\u00e9rifications constantes et des renvois, et en gros, c'\u00e9tait proche du chaos. <\/p>\n

      Dans ce cas, cette approche, l'approche de travail sur un document MS Word, fonctionnait avec beaucoup de frictions et cr\u00e9ait des probl\u00e8mes.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nConfronter le probl\u00e8me d\u00e9crit dans l'exemple ci-dessus m'a pouss\u00e9 \u00e0 explorer cette question.
      \nJ'ai constat\u00e9 que l'utilisation de       Markdown<\/a><\/noindex> de plus en plus populaire en Git<\/a><\/noindex> cr\u00e9ant des documents.<\/p>\n

      Git est un outil de d\u00e9veloppement. Mais pourquoi ne pas l'utiliser pour le processus de documentation ? Dans ce cas, la question du travail collaboratif est r\u00e9solue. Mais pour tirer pleinement parti des capacit\u00e9s 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. <\/p>\n

      Markdown est un langage de balisage textuel simple. Il est con\u00e7u pour cr\u00e9er des textes bien format\u00e9s dans des fichiers au format TXT. Si nous cr\u00e9ons nos documents en Markdown, l'association Markdown - Git semble naturelle.<\/p>\n

      Tout serait bien, et \u00e0 ce stade, on pourrait mettre un point final, si ce n'\u00e9tait pas pour notre deuxi\u00e8me condition : \u00ab nous avons besoin d'un document dans un format sp\u00e9cifique, avec des attributs de style corporate, cr\u00e9\u00e9 selon un mod\u00e8le \u00bb (et nous avons convenu au d\u00e9part que pour des raisons de clart\u00e9, il s'agira de MS Word). Donc, si nous avons d\u00e9cid\u00e9 d'utiliser Markdown, nous devons d'une mani\u00e8re ou d'une autre convertir ce fichier en .docx du format requis.<\/p>\n

      Il existe des programmes de conversion entre diff\u00e9rents formats, par exemple, Pandoc<\/a><\/noindex>.
      \nVous pouvez convertir un fichier Markdown en format .docx avec ce programme.
      \nMais 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\u00e9ritable pays compar\u00e9 \u00e0 la ville \u00e9l\u00e9gante mais petite qu'est Markdown. Il y a une \u00e9norme quantit\u00e9 de fonctionnalit\u00e9s 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\u00e9 avec certaines cl\u00e9s Pandoc. Donc, g\u00e9n\u00e9ralement, apr\u00e8s la conversion, il faut \u00ab peaufiner \u00bb le document .docx obtenu manuellement, ce qui peut encore une fois \u00eatre co\u00fbteux en termes de temps et conduire \u00e0 des erreurs.<\/p>\n

      S'il \u00e9tait possible d'\u00e9crire un script qui terminerait automatiquement ce que Pandoc n'a pas pu faire, ce serait une solution id\u00e9ale.<\/p>\n

      En raison de la non-identit\u00e9 des fonctionnalit\u00e9s de MS Word et de Markdown de mani\u00e8re g\u00e9n\u00e9rale, je pense qu'il est impossible de r\u00e9soudre cette t\u00e2che, mais peut-on le faire en fonction de situations sp\u00e9cifiques, de besoins concrets ? Mon exp\u00e9rience a montr\u00e9 que oui, c'est possible et probablement r\u00e9alisable pour de nombreuses, voire la plupart des situations. <\/p>\n

      Solution d'une t\u00e2che particuli\u00e8re<\/h3>\n

      \nDans mon cas, apr\u00e8s avoir converti le fichier \u00e0 l'aide de Pandoc, j'ai d\u00fb traiter manuellement les fichiers, \u00e0 savoir<\/p>\n