Documentation technique
Organisation
LOCAL et PROD, procédures détaillées
Format
Markdown, GitLab Wiki, Procédures
Public cible
Équipe DevOps, Développeurs, Administrateurs système
Avantages obtenus
- Clarté et transparence des processus
- Gain de temps lors de l'installation de logiciels
- Facilitation de la collaboration en équipe
- Continuité des opérations assurée
Présentation du projet
Tout au long de ce projet, j'ai effectué des documentations que j'ai déposées dans un dépôt GitLab nicomatic. Cette documentation est conçue pour aider l'équipe DevOps à comprendre comment mon infrastructure est faite, et principalement permettre un gain de temps lors de l'installation de logiciels et d'outils.
J'ai organisé mes documentations en deux sections principales : LOCAL et PROD, chacune contenant des guides et des procédures spécifiques pour configurer et gérer l'infrastructure dans les environnements respectifs. Cette approche structurée garantit que les informations sont facilement accessibles et pertinentes pour les différents contextes d'utilisation.
Structure de la documentation
Section LOCAL
La section LOCAL contient des guides et des procédures pour configurer et gérer l'infrastructure en environnement local. Ces documents couvrent divers aspects essentiels au développement.
Documents inclus
- environment-dev-local.md
- procedure-creation-cle-ssh-on-ubuntu-wsl.md
- procedure-installation-docker-on-ubuntu-wsl.md
- procedure-installation-git-on-ubuntu-wsl.md
- procedure-installation-ssh-on-ubuntu-wsl.md
Section PROD
La section PROD contient des documentations spécifiques à l'environnement de production. Ces documents sont essentiels pour garantir que le déploiement et la gestion des services en production se déroulent sans encombre.
Documents inclus
- procedure-automatisation-GitLab-CI-CD.md
- procedure-configuration-GitLab.md
- procedure-hebergement-website-on-aws.md
- procedure-start-project.md
- procedure-troubleshooting-docusaurus.md
Défis techniques
Organisation de l'information
Structurer la documentation de manière logique et accessible pour différents publics et cas d'usage.
Solution mise en œuvre
J'ai adopté une structure à deux niveaux (LOCAL et PROD) pour séparer clairement les environnements, puis organisé les documents par thématique et cas d'usage. Chaque document suit un format standardisé avec des sections claires pour faciliter la navigation.
Niveau de détail approprié
Trouver le bon équilibre entre des instructions détaillées et une documentation concise et utilisable.
Solution mise en œuvre
J'ai utilisé une approche par étapes numérotées pour les procédures, avec des explications claires à chaque étape. Pour les concepts plus complexes, j'ai ajouté des sections d'explication supplémentaires et des exemples concrets. J'ai également inclus des captures d'écran pour les étapes critiques.
Intégration avec GitLab
Assurer que la documentation reste accessible, à jour et bien intégrée avec les projets GitLab.
Solution mise en œuvre
J'ai utilisé le format Markdown pour tous les documents, ce qui permet une excellente compatibilité avec GitLab. J'ai également mis en place des liens entre les documents et les projets concernés, et organisé le dépôt de documentation avec une structure de dossiers claire reflétant les sections LOCAL et PROD.
Avantages de la documentation
Clarté et transparence
La documentation aide à clarifier le fonctionnement de l'infrastructure et des processus, rendant les opérations plus transparentes pour l'équipe DevOps.
Gain de temps
En fournissant des instructions claires et détaillées, la documentation permet de gagner du temps lors de l'installation de nouveaux logiciels et outils, ainsi que lors de la résolution des problèmes.
Facilitation de la collaboration
La documentation facilite la collaboration entre les membres de l'équipe en leur fournissant un référentiel commun de connaissances et de procédures.
Continuité des opérations
En cas de changement de personnel, la documentation assure la continuité des opérations en permettant aux nouveaux membres de l'équipe de se familiariser rapidement avec l'infrastructure et les processus.
Compétences acquises
Rédaction technique
Capacité à rédiger des instructions claires, précises et faciles à suivre pour différents publics techniques
Markdown
Maîtrise du langage de balisage Markdown pour créer des documents bien structurés et formatés
Gestion de la documentation
Organisation et maintenance d'un système de documentation cohérent et à jour
GitLab Wiki et dépôts
Utilisation efficace des fonctionnalités de GitLab pour héberger et partager la documentation
Conclusion
La création et le dépôt de la documentation dans GitLab ont permis d'assurer une meilleure compréhension et une gestion plus efficace de l'infrastructure, tout en améliorant la collaboration au sein de l'équipe DevOps. Cette documentation sert non seulement de référence pour les opérations actuelles, mais aussi de base solide pour les futurs développements et améliorations.
En investissant du temps dans la création d'une documentation de qualité, j'ai contribué à la résilience et à l'efficacité de l'équipe, tout en développant des compétences précieuses en communication technique et en gestion des connaissances. Ces compétences sont transférables à d'autres projets et contextes professionnels, renforçant ainsi ma valeur en tant que professionnel de l'informatique.