Dans ce billet, l’auteur souligne que les équipes de développement évoluent constamment avec les arrivées et les départs de membres, ce qui crée à chaque fois une nouvelle dynamique d’équipe. Ces changements entraînent des pertes de connaissances non documentées ou des décisions implicites, mais aussi l’apport de nouvelles perspectives. Pour atténuer les perturbations, il est crucial d’avoir une documentation claire, une vision partagée et des standards de développement bien définis (architecture, choix techniques, processus de revue de code, stratégie de tests, etc.). Ces éléments permettent de maintenir une cohérence et une direction commune, même lorsque la composition de l’équipe change. L’idéal serait d’automatiser cette documentation pour qu’elle reste toujours à jour et accessible, assurant ainsi la stabilité du projet sur le long terme.
Les fichiers .http offrent une alternative légère et efficace aux outils comme Postman pour tester et documenter des APIs directement depuis un éditeur de code. Ces fichiers texte, basés sur la syntaxe HTTP standard, permettent de décrire, versionner et exécuter des requêtes HTTP sans dépendre d’un outil externe ou d’un compte cloud. Intégrés nativement dans des IDE comme VS Code (via l’extension REST Client) ou JetBrains, ils facilitent le versionnement avec Git, la collaboration via des pull requests, et servent de documentation vivante pour les APIs. Leur simplicité et leur indépendance technologique en font un choix idéal pour les équipes souhaitant éviter les outils lourds et centraliser leurs tests d’API dans leur repository. L’article propose des exemples concrets avec les APIs publiques françaises (comme l’API Geo et Adresse), montre comment gérer les variables et environnements, et explique comment automatiser ces tests dans des pipelines CI/CD avec des outils comme httpyac. Une solution pragmatique pour les développeurs cherchant à simplifier leur workflow tout en gardant une documentation et des tests à jour.
L’article de Stack Overflow souligne que le rôle d’un architecte logiciel ne se limite pas à écrire du code, mais consiste surtout à déployer des idées dans des systèmes humains : convaincre, aligner et faire collaborer des équipes aux perspectives variées. Pour cela, le principal outil de l’architecte n’est pas un langage de programmation, mais la rédaction de documents clairs et structurés.
Points clés :
- La documentation comme levier : Les architectes utilisent des documents (Confluence, Google Docs, Notion, etc.) pour formaliser des propositions, des designs techniques ou des analyses, et ainsi obtenir l’adhésion des parties prenantes.
- Principe de base : Privilégier la simplicité (bullet points, titres clairs) et l’utilité immédiate plutôt que la perfection formelle. Un document doit permettre à chacun de trouver rapidement l’information dont il a besoin.
- Types de documents impactants :
- Architecture overview : Schéma ou description des composants d’un système pour faciliter la compréhension et l’onboarding.
- Dev design : Détail des modifications prévues pour recueillir des feedbacks avant de coder.
- Project proposal : Argumentaire pour justifier l’allocation de ressources à un projet.
- Developer forecast : Alerte sur les risques potentiels d’une décision technique.
- Technology menu : Guide pour standardiser les choix technologiques.
- Problem statement : Cadre pour résoudre un problème complexe en équipe.
- Postmortem : Analyse blameless d’un incident pour éviter sa répétition.
Méthode recommandée :
- Organisation chronologique : Classer les documents par sprint/année plutôt que par thème, car la recherche textuelle est plus efficace que la navigation par dossiers.
- Culture de la documentation : Encourager l’écriture rapide et itérative, avec des relectures ciblées, plutôt que des mises à jour constantes.
- Objectif : Rendre les idées accessibles, actionnables et pérennes, même si le document devient obsolète.
En résumé, un architecte excelle moins par sa maîtrise technique que par sa capacité à structurer et communiquer des idées pour faire avancer les projets, en transformant les blocages humains en processus collaboratifs. Une compétence clé pour ceux qui veulent rester techniques tout en élargissant leur impact.
EventCatalog est un outil open source qui comble un manque crucial dans les architectures orientées événements : la documentation claire et maintenable. En adoptant une approche "documentation-as-code", il permet de décrire et visualiser les messages (événements, commandes, requêtes), les canaux de communication, les domaines, services et entités (inspirés du Domain-Driven Design), ainsi que les équipes et le langage ubiquitaire. Intégrable avec des registres de schémas (OpenAPI, AsyncAPI, JSON, Avro), il automatise la génération de documentation interactive, facilitant la compréhension et la maintenance des systèmes asynchrones. Grâce à des fonctionnalités comme les graphes de dépendances, la visualisation des schémas et la gestion des équipes, EventCatalog rend accessible et vivante la complexité des architectures événementielles, tout en restant simple à déployer et à mettre à jour. Une solution idéale pour aligner documentation et développement, surtout dans des écosystèmes distribués.
L'article explore l'importance des messages de commit clairs et de la documentation complète dans le processus de développement logiciel. L'auteur y décrit sa routine personnelle pour rédiger des messages de commit détaillés et structurés, en utilisant un modèle standard qui inclut le type de modification, la portée, un résumé, une description du problème, la solution apportée, et le contexte supplémentaire. Il souligne également l'impact positif de cette pratique sur la collaboration et la maintenance du code. L'article aborde aussi l'utilisation d'outils comme les hooks Git pour maintenir la qualité des commits et l'intégration de l'IA pour aider à la documentation. Enfin, l'auteur partage son approche pour gérer la documentation à travers différentes étapes du développement, soulignant que ces pratiques sont essentielles pour un développement professionnel efficace.
L'article explore les meilleures pratiques pour rédiger une documentation technique efficace. Il aborde des aspects clés comme la perspective du lecteur, l'accessibilité, les boucles de rétroaction, et les techniques de rédaction. L'auteur souligne l'importance de connaître son audience, d'utiliser un langage clair et des diagrammes bien structurés. Un guide essentiel pour créer des documents techniques utiles et accessibles.
L'auteur insiste sur la nécessité d'écrire : écrire pour documenter la vision, écrire pour réfléchir, écrire pour discuter, etc. C'est une compétence indispensable pour toute personne senior
Tout est dans le titre
La documentation de plein de langages / frameworks rassemblée en un seul site
Présentation de Starlight, un template Astro pour la documentation
Tout est dans le titre
Tout est dans le titre
L'auteur résume une conférence expliquant comment structurer la documentation
Tout est dans le titre
De la doc et manuels informatiques
D'après la documentation, le module doctest cherche des extraits de texte ressemblant à des sessions Python interactives avant de les exécuter, de façon à vérifier que le fonctionnement correspond exactement à la description.
et d'après l'article, il s'agit surtout d'une documentation testée. J'aime beaucoup le principe
Tout est dans le titre
L'auteur effectue le refactoring d'un test en appliquant plusieurs techniques / idées pour le rendre plus lisible.... très intéressant
Tout est dans le titre
L'auteur explique l'intérêt d'utiliser Asciidoc pour générer sa documentation