[fusion_builder_container hundred_percent="no" hundred_percent_height="no" hundred_percent_height_scroll="no" hundred_percent_height_center_content="yes" equal_height_columns="no" menu_anchor="" hide_on_mobile="small-visibility,medium-visibility,large-visibility" status="published" publish_date="" class="" id="" background_color="" background_image="" background_position="center center" background_repeat="no-repeat" fade="no" background_parallax="none" enable_mobile="no" parallax_speed="0.3" video_mp4="" video_webm="" video_ogv="" video_url="" video_aspect_ratio="16:9" video_loop="yes" video_mute="yes" video_preview_image="" border_size="" border_color="" border_style="solid" margin_top="" margin_bottom="" padding_top="" padding_right="" padding_bottom="" padding_left=""][fusion_builder_row][fusion_builder_column type="2_3" layout="2_3" spacing="" center_content="no" link="" target="_self" min_height="" hide_on_mobile="small-visibility,medium-visibility,large-visibility" class="" id="" background_color="" background_image="" background_image_id="" background_position="left top" background_repeat="no-repeat" hover_type="none" border_size="0" border_color="" border_style="solid" border_position="all" border_radius="" box_shadow="no" dimension_box_shadow="" box_shadow_blur="0" box_shadow_spread="0" box_shadow_color="" box_shadow_style="" padding_top="" padding_right="" padding_bottom="" padding_left="" margin_top="" margin_bottom="" animation_type="" animation_direction="left" animation_speed="0.3" animation_offset="" last="no"][fusion_text columns="" column_min_width="" column_spacing="" rule_style="default" rule_size="" rule_color="" hide_on_mobile="small-visibility,medium-visibility,large-visibility" class="" id=""]
Depuis plus de 20 ans que je fais de l'informatique, un gros point noir dans le travail est la mise en place des documentations et/ou procédures. Que ce soit les procédures techniques à l'époque ou j'étais technicien pc, ls procédures quand j'étais responsable d'activité ou ces dernières années en tant qu’administrateur système, documenter les installations du quotidiens.
Dans notre métiers d'admin Linux on pratique sur beaucoup de domaines, à un moment on prépare un vhost, quelques minutes plus tard un petit script pour faire du ménage dans les données, puis plus tard la mise en place de conteneurs et encore quelques minutes plus tard on déploie un cluster d'indexation. Il est difficile de connaître tout cela par cœur tellement les techniques, les configurations et les compétences peuvent être différentes.
Il est donc important de documenter les installations de façon à pouvoir les reproduire plus tard ou faire des corrections. Encore plus important quand on développe une entreprise pour que la connaissance et la compétence soit partagées auprès des collaborateurs. Souvent on se dis, la doc je la ferais plus tard, on prends quelques notes dans un fichier texte, voir sur un bout de papier et le plus tard n'arrive jamais.
Tout au long de ma carrière je suis passé par plusieurs modèles de mise en place de docs, que ce soit des procédures papier, des procédures en doc ou pdf, puis des wiki, des blogs comme celui-ci.
Ces dernières années avec la création de différentes entreprises, il a fallut de plus en plus mettre en place des processus qui permettent de déployer facilement et rapidement les documentations, quand je dis rapidement c'est qu'une fois que j'ai fini d'éditer la doc elle doit être disponible pour tout le monde ... tiens ça ressemble beaucoup au principe de déploiement automatisé des applications mis en place avec les méthodes devops.
A partir de ce principe nous avons commencé à mettre en place ces idées, première étape une rédaction facile et rapide, le format markdown et l'édition des fichiers via un bon vieux VI était pour moi le plus élémentaire, je tape les commandes dans une console et les copies dans le fichier markdown via VI. L'avantage du markdown est que la courbe d'apprentissage du langage est très rapide et donc la documentation s'écrit facilement. Mes outils : terminator et VI.
Une fois que les fichiers markdown sont écrit il faut les transformer en html, Jules à alors proposé mkdocs avec quelques addons. On organise un peu le projet, on crée le fichier d'index de mkdocs et c'est parti. Enfin presque ...
Pour travailler sur les docs, suivre les modifications et travailler à plusieurs, il faut un outils, le mieux est d'utiliser un outils de versionning, le choix de git c'est imposé dès le début, un petit peu d'apprentissage, faire les pull, les commit et la doc est versionnée. Pour centraliser tout cela on avait déjà un gitlab en place pour certains projets clients, donc les docs ont été rapidement centralisée sur ce gitlab.
Mais comment fait on le liens entre l'édition des markdown sur nos Pc et la mise en place de fichiers html sur un serveur web pour que les docs soient lisibles par tous ?
La première étape à été de mettre en place un webhook entre gitlab et le serveur web. Dans le principe,j'édite mon fichier markdown, je le commit et quand je considère que ma version est bonne je push sur le serveur gitlab, quand celui-ci reçoit le push il va envoyer une requête POST vers un script PHP qui va exécuter un script bash (après quelques vérifications par sécurité). Le script bash pull le code et exécute mkdocs pour générer les fichiers html. Franchement ça marche très bien, c'est ce que nous mettons en place aussi pour automatiser le déploiement des applications de nos clients.
Cette année nous avons décidé de passer à une nouvelle étape, intégrer le déploiement de nos docs avec des méthodes devops plus avancées de façon à fluidifier le déploiement en continu des docs. Les webhook c'est bien mais un peu long à mettre en place pour une nouvelle doc. Jules qui travaille depuis un an sur les méthodes et outils devops à donc fait évoluer ce process en intégrant les outils suivants : gitlab-ci pour gérer le déploiement, docker et docker-compose pour isoler chaque documentation, traefik pour gérer automatiquement la partie proxy http/https en frontal de toutes les docs.
Côté rédaction ce qui est intéressant c'est que le processus n’a pas changé, on rédige les docs en markdown, on les commit et push et c'est parti, aucun changement par rapport à la méthode avec les webhook.
Dernier outils rajouté sur toute cette pile d'outils c'est keycloak pour la partie gestion des authentifications, l'idée était de tester le produit et de voir comment on peut l'utiliser, au final certaines docs seront accessibles par nos admins et d'autres par nos clients, il nous fallait donc un outils pour gérer les authentification et les autorisations.
En conclusion, une belle chaîne d'outils qui permettent de déployer facilement nos docs en mettant en place des méthodes identiques aux méthodes des développeurs. Plus d'excuse pour ne plus documenter !!!
Vous trouverez les liens vers les outils utilisez, si vous voulez des conseils hésitez pas à nous contacter.
[/fusion_text][/fusion_builder_column][fusion_builder_column type="1_3" layout="1_3" spacing="" center_content="no" link="" target="_self" min_height="" hide_on_mobile="small-visibility,medium-visibility,large-visibility" class="" id="" background_color="" background_image="" background_image_id="" background_position="left top" background_repeat="no-repeat" hover_type="none" border_size="0" border_color="" border_style="solid" border_position="all" border_radius="" box_shadow="no" dimension_box_shadow="" box_shadow_blur="0" box_shadow_spread="0" box_shadow_color="" box_shadow_style="" padding_top="" padding_right="" padding_bottom="" padding_left="" margin_top="" margin_bottom="" animation_type="" animation_direction="left" animation_speed="0.3" animation_offset="" last="no"][fusion_text columns="" column_min_width="" column_spacing="" rule_style="default" rule_size="" rule_color="" hide_on_mobile="small-visibility,medium-visibility,large-visibility" class="" id=""]
[/fusion_text][/fusion_builder_column][/fusion_builder_row][/fusion_builder_container]