Article original : How to Write Documentation For Your Next Software Development Project
Par Kevin Hanson
Avez-vous un nouveau projet logiciel à l'horizon ? Vous devriez vous préparer pour le succès. Le processus de développement détermine le résultat. Et une partie cruciale pour s'assurer que tout se passe bien est d'avoir la bonne documentation en place.
Avant de commencer à concevoir, coder, construire et tester, prenez le temps de préparer toute la documentation logicielle dont vous avez besoin. Ce n'est pas la partie la plus excitante d'un projet logiciel, mais cela fait toute la différence.
À quel point la documentation est-elle importante ?
L'industrie du logiciel est particulièrement rapide. Pour suivre le rythme, vous pourriez vouloir commencer à développer dès que vous avez une grande idée. Mais retenez vos chevaux. Prendre des raccourcis ne vous mènera pas plus loin.
Le temps passé sur la documentation plutôt que sur le développement n'est pas perdu. Au contraire, si elle est bien faite, elle vous fera non seulement gagner du temps, mais améliorera également votre produit. À mesure qu'un projet prend de l'ampleur, la documentation servira de guide pour faire les choses correctement dès la première tentative. Pas de devinettes ni d'improvisation.
Un chef de projet qui a une excellente vue d'ensemble du projet dans sa tête est formidable, mais les développeurs ou les nouveaux membres de l'équipe ne peuvent pas y accéder. Les détails peuvent se perdre dans la communication.
La documentation technique peut faire ou défaire un projet. Si chaque étape d'un projet est bien documentée, il peut se dérouler sans heurts et gagner du temps. Pas besoin de conversations en tête-à-tête pour donner les bonnes informations aux bonnes personnes, et donc pas de malentendus.
Pourquoi rédiger une documentation de projet ?
Votre projet dépendra moins des individus
Avec une documentation détaillée, l'intégration de nouveaux membres de l'équipe devient un jeu d'enfant. Lorsque votre produit grandit, change et évolue, vous pouvez facilement diriger les nouveaux talents vers la documentation nécessaire et les mettre en route en un rien de temps.
Cela fonctionne aussi dans l'autre sens : si un membre de l'équipe part, il n'emporte pas toutes ses connaissances sur le projet avec lui. Elles restent dans la documentation.
Un projet avec une excellente documentation dépend simplement moins des individus qui y travaillent. Il a son propre cadre que tout le monde devrait pouvoir utiliser. Cela rend votre projet logiciel plus résilient face aux défis inattendus.
La communication avec les parties prenantes et les clients devient plus facile
Mais les avantages d'avoir un projet logiciel bien documenté vont au-delà des processus internes.
Avec la bonne documentation, il devient également plus facile de présenter votre produit aux parties prenantes, rendant plus compréhensible ce que vous allez créer. Tout ce qui est sur papier est plus facile à examiner et à comprendre que les idées dans votre tête.
La documentation pour votre produit aide dans le processus de présentation, mais aussi lorsque vous êtes plus avancé dans le projet. Si un client a approuvé les documents que vous avez présentés, il est facile de s'y référer en cas de problème. Pas de "il a dit, elle a dit" : tout est là, prêt à être consulté.
À la fin de la journée, un projet réussi ne concerne pas seulement le produit que vous construisez, mais aussi les relations que vous avez construites. Prévoyez tout problème possible et assurez une collaboration agréable.
Comment rédiger une bonne documentation
Tout cela ne nécessite pas une documentation de type encyclopédie. Assurez-vous simplement de couvrir les essentiels pour votre projet en particulier. Dans cet article, nous vous donnerons quelques conseils sur la manière de procéder.
Faites un inventaire des documents dont vous aurez besoin
Avez-vous déjà tout votre projet planifié dans votre tête ? C'est un excellent début, mais je recommanderais tout de même de le documenter. Si vous ne voyez pas l'intérêt de créer une quelconque documentation pour vous-même, rappelez-vous que vous le faites principalement pour les utilisateurs de votre projet final.
Ils le remarqueront : non seulement dans le fonctionnement de l'outil logiciel, mais aussi dans la rapidité de sa livraison, sans que vous ayez à faire beaucoup de changements après le lancement.
Mais de quels types de documents aurez-vous réellement besoin ? Selon la taille du projet, vous pourriez avoir besoin de documentation qui guidera les processus quotidiens. Ou peut-être avez-vous surtout besoin d'un cadre pour la vision d'ensemble.
Divisons la documentation logicielle en deux catégories : la documentation de processus et la documentation de produit.
Qu'est-ce que la documentation de produit ?
La documentation de produit décrit l'objectif final : le produit réel que vous construisez. Comment il fonctionne, comment travailler avec, les spécifications technologiques, les manuels, tout ce que vous devez savoir une fois que le produit existe.
Pour vos développeurs, la documentation la plus importante est la documentation système. Elle explique comment le produit logiciel fonctionne, pourquoi il fonctionne d'une certaine manière et comment travailler avec.
Pour les utilisateurs finaux de votre produit logiciel, la documentation utilisateur est essentielle. Pensez aux tutoriels, aux FAQ pour le dépannage et à un manuel qui les aidera à utiliser et à aimer votre produit comme vous l'aviez prévu.
Qu'est-ce que la documentation de processus ?
Considérez cela comme la feuille de route qui mènera votre projet de l'idée à l'existence. Vous pouvez y inclure :
- Normes et plannings de test : assurez-vous que tout le monde teste votre produit de la même manière, afin que les résultats soient réellement pertinents.
- Comptes-rendus de réunion : sauvegardez-les, afin de pouvoir les remettre à votre client en cas de désaccord.
- Plans de projet : comment allez-vous construire votre produit ? Quelles étapes souhaitez-vous atteindre en cours de route et quand ?
Déterminez les informations cruciales
Dans votre documentation de processus, vous pouvez décider à quel point vous allez détailler les étapes et le processus. Si vous êtes un développeur logiciel ou un chef de projet expérimenté, vous saurez quelles questions sont susceptibles de se poser et quelles discussions vont surgir.
Si vous êtes nouveau dans ce domaine, vous pourriez être perdu quant à ce que vous pouvez ou devez inclure. Voici quelques exemples que vous pourriez négliger ou auxquels vous ne penseriez pas, mais qui peuvent accélérer le développement de votre projet.
Conformité des données et de la vie privée
Si cela est pertinent pour votre produit, créez des directives qui aideront votre équipe à rester dans les limites de ce qui est autorisé en matière de réglementation des données. Quelles règles sont en place ? Quel processus les employés doivent-ils suivre pour savoir qu'ils sont en sécurité ?
Plans d'urgence
Que faites-vous lorsque votre serveur tombe en panne ? Quelle est la première étape après une faille de sécurité ? Que se passe-t-il si votre matériel décide demain qu'il ne veut plus fonctionner ? Avoir des réponses à des questions comme celles-ci peut vous faire économiser beaucoup de temps et d'argent.
Documentation visuelle
Ne vous inquiétez pas, designers, la documentation technique n'est pas seulement des mots. Les gens sont encore principalement des penseurs visuels. C'est pourquoi les diagrammes peuvent vous aider à rendre les flux de travail plus clairs.
Mais les visuels qui expliquent comment le produit devrait fonctionner à la fin du projet contribuent également à une manière de travailler plus rationalisée, surtout si ce que vous construisez est assez complexe.
Toujours incertain de ce qu'il faut inclure ? Demandez aux personnes concernées. Réunissez votre équipe autour de la table et déterminez ensemble ce qu'ils veulent avoir sur papier pour prévenir les problèmes à l'avenir.
Rédigez des documents techniques efficaces
Ne vous inquiétez pas, je vais vraiment vous dire comment faire. La plupart des gens ne naissent pas écrivains, et encore moins rédacteurs techniques. Rédiger des documents techniques peut sembler une tâche ennuyeuse et en même temps intimidante. Après tout, faire une erreur dans un document technique pourrait avoir des implications assez importantes pour le produit ou le processus. Faire une erreur dans un manuel utilisateur pourrait aussi.
Surveillez votre langage
Vous n'avez pas besoin d'impressionner qui que ce soit avec un document technique. Vos membres d'équipe sauront que vous êtes compétent, sans que vous utilisiez du jargon là où ce n'est simplement pas nécessaire.
Beaucoup de gens ressentent le besoin d'écrire un langage beaucoup plus difficile lorsqu'il s'agit de documents liés aux affaires. Mais vous traitez toujours avec des personnes, des humains à qui vous parlez d'une certaine manière. Essayez d'utiliser cette manière de parler dans votre écriture également pour rendre vos documents plus compréhensibles.
Gardez vos phrases courtes. Simplifiez vos mots. Évitez les malentendus.
Le but de la documentation technique est de clarifier les choses et d'accélérer les processus. Pas de produire plus de questions. Cela s'applique encore plus aux documents destinés à l'utilisateur final.
Pour des points bonus, rédigez différentes documentations en fonction de différents personas d'utilisateurs. Prenez Python par exemple, qui possède une excellente documentation pour une variété d'utilisateurs, des débutants aux professionnels expérimentés.
Organisez vos pensées
Oui, si vous prévoyez d'écrire un plan, vous aurez besoin d'un plan pour l'écrire. Avoir une structure claire dans votre documentation technique est ce qui fera gagner du temps aux lecteurs et aux utilisateurs. Utilisez des en-têtes. Trouvez un ordre chronologique.
Si c'est votre première fois, commencez simplement par utiliser un modèle pour votre document technique. Vous n'avez pas besoin de réinventer la roue.
Il est temps de tester
Faites lire votre documentation technique à quelqu'un d'autre pour vous assurer qu'elle est facile à comprendre et couvre tous les aspects pertinents.
Trop souvent, les manuels utilisateur ne sont considérés que comme un sous-produit et ne sont pas inclus dans les tests. Préparez-vous pour le succès en l'incluant dans vos tests et votre développement.
Rendez-vous service pour les projets futurs
Créer une documentation technique ne profite pas seulement au projet sur lequel vous travaillez actuellement. Cela peut également aider les projets futurs, car le cadre est déjà en place. Il suffit de faire les changements nécessaires en fonction de votre produit et de votre expérience passée, et vous êtes prêt à commencer le développement.