Documentation Lisible par l'IA

Actuellement, il y a beaucoup d'agitation autour d'un outil de développement appelé GitHub Copilot, qui est doté de fonctionnalités assistées par l'IA. Il semble y avoir une idée fausse selon laquelle cet outil n'est destiné qu'aux ingénieurs. Bien que cela soit partiellement vrai, cela est également partiellement incorrect. En effet, GitHub Copilot a une capacité incroyable à transformer la façon dont les ingénieurs travaillent. Cependant, à mesure que les méthodes de travail des ingénieurs changent, les organisations doivent également s'adapter. Si vous êtes en position de gestion de projet ou de propriétaire de produit, il s'agit d'une question importante pour vous également. Puisque les ingénieurs de votre équipe sont censés donner le meilleur d'eux-mêmes et mettre en œuvre rapidement vos exigences définies. À l'avenir, même si vous n'êtes pas un ingénieur, vous devrez créer des documents lisibles par l'IA pour permettre à vos ingénieurs de travailler avec l'IA.

Culture de la documentation et développement natif de l'IA

Ces dernières années, la technologie de l'IA a progressé rapidement, avec des modèles tels que LLM (Large Language Model) attirant l'attention. GitHub, une plateforme de développement open-source, s'est également aventuré dans le domaine du développement de l'IA. Un exemple principal de cela est "GitHub Copilot". Curieusement, le développement assisté par l'IA et le développement open-source partagent des points communs en termes de collaboration. Plus précisément, les deux méthodes impliquent de travailler avec des formats basés sur des documents tels que Markdown. Des formats tels que Markdown sont conçus pour représenter des informations structurées et sont plus faciles à analyser par l'IA que les fichiers PowerPoint ou Excel. Par conséquent, ils contribuent à l'amélioration de la qualité du code généré par l'IA.

L'IA préfère les fichiers CSV simples aux feuilles de calcul Excel complexes remplies de métadonnées. Si vous, en tant que gestionnaire de projet, énumérez les exigences des clients et recueillez les informations nécessaires pour une base de données. Si les exigences sont écrites dans un fichier CSV ou résumées dans Markdown, les ingénieurs peuvent facilement les convertir en code. Cependant, si vous compilez les informations dans un document Excel adapté à vos préférences, les ingénieurs doivent d'abord copier, formater, puis le convertir en code. Quelle approche est meilleure?

De plus, dans le développement open-source, la qualité de la documentation peut être directement liée au succès d'un projet. Les projets open-source sont ouverts à tous et une documentation correctement entretenue permet aux nouveaux développeurs de s'impliquer plus facilement. Par conséquent, la documentation est très valorisée dans le développement open-source. De même, dans le développement de l'IA, une culture de documentation bien établie peut conduire à un développement plus efficace et de meilleure qualité. Même si vous n'êtes pas un ingénieur, votre langue naturelle écrite en Markdown peut contribuer de manière significative à la production finale, qui est le code. Il peut s'ag ir du code représentant la logique métier, des définitions de tables ou même des scénarios de test. Votre équipe de développement est-elle prête à inclure l'IA ? Les documents lisibles par l'IA sont-ils préparés ? Si la réponse est non, vous devez commencer à créer une équipe de développement à l'aise pour travailler avec l'IA.

Développement natif de l'IA et stratégie InnerSource

Nous avons parlé du développement open-source, mais il existe également un concept similaire appelé InnerSource. InnerSource est une approche qui adopte les meilleures pratiques du développement de logiciels open-source au sein des organisations qui développent des logiciels non open-source ou propriétaires. Il vise à favoriser la collaboration entre les différentes divisions de l'organisation et à briser les silos organisationnels.

InnerSource devient de plus en plus important pour les entreprises pour éviter de réinventer la roue, rationaliser le développement pour réduire les coûts et créer de la valeur grâce à la collaboration.

Comme mentionné sur la page de développement natif de l'IA, l'IA a tendance à augmenter les humains expérimentés. Les personnes âgées ou expérimentées au sein d'une organisation qui comprennent l'architecture sont renforcées, tandis que les autres se voient attribuer des tâches plus simples.

Cependant, puisque l'IA est principalement formée sur la base de connaissances provenant d'Internet, elle ne peut pas accéder aux domaines propriétaires, aux connaissances fermées au sein des organisations ou aux informations non publiées. Par conséquent, si ces informations ne sont pas documentées ou partagées correctement au sein de l'organisation, cela pose un problème. Ce problème signifie que non seulement les ingénieurs ne peuvent pas accéder aux informations, mais l'IA comme GitHub Copilot ne peut pas non plus y accéder.

Les connaissances qui ne peuvent pas être obtenues à partir d'Internet deviennent actuellement plus importantes et une compétence essentielle des entreprises. Il y a une citation d'un livre d'introduction à InnerSource "Getting Started with InnerSource" d'O'Reilly :

InnerSource diffère de l'open-source classique en restant dans la vue et le contrôle d'une seule organisation. L'« ouverture » du projet s'étend à de nombreuses équipes au sein de l'organisation. Cela permet à l'organisation d'intégrer des secrets commerciaux différenciants dans le code sans craindre qu'ils ne soient révélés à des personnes extérieures, tout en bénéficiant de la créativité et des perspectives diverses apportées par les personnes de toute l'organisation.

De nombreuses entreprises sont confrontées au choix de collaborer avec l'IA ou d'être remplacées par l'IA. Il est essentiel d'agréger les informations internes qui sont la source de l'avantage concurrentiel de l'organisation et de les faire utiliser par l'IA. Pour y parvenir, une documentation lisible par l'IA est indispensable.

En ce qui concerne InnerSource, il existe déjà une communauté mature où les méthodes pour réaliser la co-création au sein des organisations et créer de la documentation sont partagées. Accédez à cette communauté et tirez parti des initiatives InnerSource. En faisant cela, vous pouvez utiliser efficacement les connaissances et les informations internes et tirer le meilleur parti de la collaboration avec l'IA.

Références InnerSource

• InnerSource Commons : page de la Fondation InnerSource Commons

• InnerSource Patterns : collection de meilleures pratiques InnerSource

• Getting Started with InnerSource : livre d'introduction InnerSource d'O'Reilly

• Understanding the InnerSource Checklist : guide pratique InnerSource d'O'Reilly

Créer une documentation riche en contexte

À mesure que le développement open-source se développe, la collaboration entre les pays et les fuseaux horaires émerge. Cependant, la distance géographique et les différences de fuseau horaire peuvent parfois rendre la communication synchrone difficile. Par exemple, le jour à New York est la nuit à Tokyo, et il n'est pas souhaitable de déranger les contributeurs basés au Japon la nuit ou d'interférer avec le temps familial. Par conséquent, la documentation basée sur des documents écrits est généralement préférée. Il pourrait s'agir de quelque chose comme des RFC ou des documents de conception, ou de commentaires écrits dans les problèmes GitHub. Les documents formés par des commentaires dans les problèmes et similaires sont également appelés documentation passive. Ce sont aussi des formes de documentation.

Il y a une passage dans Understanding the InnerSource Checklist publié par O'Reilly qui dit ceci :

La documentation passive est l'enregistrement de la documentation que nous créons chaque jour en communiquant ouvertement. C'est un excellent moyen d'obtenir des connaissances tribales hors des silos et dans un format archivable et trouvable. En prime, elle est généralement conservée avec le projet ou le code qu'elle documente, ce qui la rend facile à trouver et pertinente dans son contexte.

Ce qui est important ici, c'est de bien le mettre en mots, y compris le contexte. Il est difficile de transmettre la communication non verbale, les nuances et l'atmosphère qui sont communiquées via Zoom ou des conversations en face à face de manière asynchrone à travers les fuseaux horaires.

Considérez le développement avec l'IA. Par exemple, GitHub Copilot participera-t-il aux réunions Zoom ? Serait-il dans la salle de l'équipe en disant : "Hey, je suis GitHub Copilot, faisons une réunion de suivi rapide" ? La réponse est non. Tout le contexte doit être transmis à l'IA par écrit. C'est également nécessaire lors de la création d'une documentation appropriée pour une communication asynchrone, comme dans le développement open-source.

Bien sûr, il y a des différences dans la granularité de la documentation entre le développement open-source et le développement assisté par l'IA. Écrire "Je veux corriger ce bogue" dans les problèmes GitHub pourrait inciter quelqu'un à penser à une solution, mais l'IA ne peut pas aller aussi loin. Cependant, il existe certainement des domaines dans lesquels l'IA excelle. Si vous voulez exprimer une architecture cloud en tant qu'infrastructure en code, il est préférable de l'écrire en Mermaid ou de l'exprimer en langage naturel plutôt que de la dessiner dans PowerPoint.

Le point ici n'est pas que toute communication doit être documentée. Vous et votre équipe devez réfléchir au niveau de documentation à laisser, comment et où la laisser.

La coordination de la connaissance organisationnelle par l'IA

Avec des fonctionnalités telles que GitHub Copilot pour les documents inclus dans GitHub Copilot X, l'IA peut créer la documentation parfaite pour vous. Les documents que vous écrivez peuvent également devenir des supports d'intégration pour la personne suivante.

Dans le passé, rassembler des informations et créer des supports d'intégration pour les nouveaux ingénieurs était une tâche courante, mais à l'avenir, l'IA prendra probablement en charge ce rôle. Vous pouvez intégrer toutes les connaissances que vous possédez dans des documents en tant que seule source fiable d'information.

Cette approche peut également être clairement vue dans la documentation d'Atlassian. La lecture de leur documentation en gardant à l'esprit le développement natif de l'IA pourrait conduire à de nouvelles découvertes. Les documents que vous écrivez sembleront avoir une personnalité grâce à l'IA. Cependant, cela nécessite une documentation suffisante, comme mentionné précédemment.

La distance entre le langage naturel et la mise en œuvre se rapproche

Comme vous l'avez peut-être déjà remarqué, la distance entre le langage naturel et la mise en œuvre se rapproche beaucoup. Comme mentionné précédemment, d'un point de vue éducatif, si l'écriture de prompts et de code dans un seul endroit continue, il sera peut-être possible de créer une documentation dans un seul fichier. Ce genre de changement est fascinant.

Liste de contrôle

• Votre équipe a-t-elle actuellement une culture de documentation ? Si oui, à quoi ressemble-t-elle ? Sinon, qu'est-ce qui l'empêche ?

• Réfléchissez à quel type de documentation est nécessaire pour que votre équipe collabore avec l'IA.

• Votre équipe a-t-elle une culture d'open source ou d'inner source ?

• Commencez par créer une culture de documentation dans votre domaine. Dans quels domaines pouvez-vous commencer à rédiger de la documentation en Markdown ? Réfléchissez-y.