Guide de rédaction de votre première documentation logicielle –

En tant que développeur, votre fierté et votre joie sont votre code. Il est lisible, il respecte les principes de DRY, il reflète les meilleures pratiques et le produit final est un excellent outil qui résout un type de problème pour ses utilisateurs cibles. Toutefois, quel que soit le travail que vous avez fait dans votre code, si votre logiciel ne contient pas de documentation ou si vous écrivez une documentation après coup et si vous la traitez avec peu d'importance, il est probable que les utilisateurs trouveront peu de joie à l'utiliser, et Pour finir, optez pour un produit différent, plus convivial.

Dans cet article, vous trouverez un certain nombre de principes directeurs pratiques vous permettant de commencer à écrire votre première documentation de logiciel.

Pourquoi la documentation est importante [19659004] En référence à votre logiciel, Mike Pope a un dicton bien approprié: S'il n'est pas documenté, il n'existe pas .

Pourquoi? Eh bien, juste pour prendre mon expérience personnelle comme exemple, je naviguais sur le Web à la recherche de nouvelles bibliothèques d’animation JavaScript et j’en trouvais une avec une description de ses fonctionnalités qui me plaisait vraiment. Cependant, il n'y avait pas de documentation, pas même une section Mise en route, mais juste une page API nue avec presque pas d'explications ou d'exemples. Pensez-vous que j'ai fini par utiliser cette bibliothèque? Bien sûr, je ne l’ai pas fait. J'étais tellement frustré que je suis passé à quelque chose qui me semblait plus logique.

À la question de pourquoi les bonnes bibliothèques JavaScript échouent-elles Nicholos Zakas donne la réponse suivante :

Manque de documentation . Quelle que soit la qualité de votre bibliothèque et sa conception intelligente, si vous êtes le seul à la comprendre, cela ne sert à rien. La documentation ne signifie pas seulement des références d'API générées automatiquement, mais également des exemples annotés et des didacticiels détaillés. Tous les trois sont nécessaires pour que votre bibliothèque puisse être facilement adoptée.

Une autre raison importante pour laquelle vos documents logiciels sont d’une importance cruciale est qu’ils servent d’outil de communication entre votre moi actuel et votre avenir, ainsi qu’entre vous-même. et d'autres développeurs qui pourraient éventuellement se retrouver à travailler sur votre logiciel. Même si vous écrivez du code lisible et commenté, cela ne signifie pas nécessairement que, dans six mois, vous comprendrez toujours pourquoi vous avez écrit une fonction, ou tout autre élément de votre code, comme vous l'avez fait. 19659009] La documentation vous permet de transférer le pourquoi derrière le code. De la même manière, les commentaires de code expliquent pourquoi le pourquoi et non le comment la documentation sert le même but. – Guide du débutant pour la rédaction de documentation

Vous voulez sûrement que les gens utilisent votre code et puissent éventuellement le mettre à jour et l’améliorer. Tous ces facteurs contribuent à la croissance d’une communauté d’appui derrière votre produit, ce qui est important pour que celui-ci gagne en robustesse, maturité et succès.

Il sera extrêmement difficile d’accomplir tout cela si votre logiciel n’a pas une excellente documentation pour l'accompagner.

Pour qui la documentation de logiciel est-elle destinée

Lorsque vous écrivez quoi que ce soit, assurez-vous de bien connaître votre public cible. Les documents ne font pas exception à cette règle. Cela clarifie dans votre tête les problèmes auxquels votre public est susceptible de faire face, la familiarité qu’il aura probablement avec votre produit ou les conditions préalables à l’utilisation de votre produit. Ces informations sont essentielles à la manière dont vous créez le contenu et à la langue que vous utilisez.

Il existe deux types de documentation qui ne concerne pas cet article:

1. Manuels d'utilisation. Par exemple, ma sœur pourrait décider d’utiliser WordPress pour publier son propre blog. Elle n’est pas une développeur, mais elle a entendu dire que les non-développeurs peuvent obtenir leur blog en un rien de temps avec WordPress. Maintenant, elle aura besoin d'instructions sur la procédure de téléchargement et de configuration du logiciel sur son serveur, comment écrire, publier et mettre à jour ses publications, comment ajouter des images à une publication, etc. En d'autres termes, elle aura besoin d'un utilisateur. manuel
2. Documentation du projet. Ce type de documentation a plus à voir avec le projet qu'avec le logiciel lui-même, même si une partie de son contenu pourrait être insérée dans le fichier Readme d’un projet. Pour continuer avec l’exemple de WordPress, après une longue pratique de WordPress, je pourrais décider si je souhaite ajouter une fonctionnalité au logiciel ou corriger un bogue ou deux. Dans ce cas, je devrai connaître des choses telles que les journaux des modifications, les conventions et les meilleures pratiques, les règles de contribution, comment participer à des discussions d'équipe ayant un rapport avec la tâche à accomplir, etc.

Le type de documentation que j'ai à l'esprit ici est principalement destiné aux développeurs ayant différents niveaux de connaissance de votre logiciel et qui ont besoin de l'utiliser dans leurs projets. Par exemple, si je crée un thème WordPress, je devrai savoir comment s'y prendre, comment inclure des feuilles de style et des documents JavaScript, comment communiquer avec la base de données pour afficher des articles, etc.

Inclure dans votre documentation

Une approche populaire est le développement basé sur un fichier Lisez-moi défendu par Tom Preston-Werner. Il consiste à écrire le document Lisez-moi avant même de commencer à écrire du code. Ce document est une introduction à votre logiciel et comprend généralement:

• une explication de ce que votre logiciel fait et du problème qu’il résout
• un exemple illustrant les circonstances dans lesquelles votre code serait normalement utilisé
• des liens vers le code and bugs tracker
• FAQ et moyens de demander de l'aide
• instructions sur l'installation de votre logiciel
• informations de licence

Cependant, à mon avis, disposer d'une documentation solide pouvant réellement aider les développeurs utilisant votre logiciel / library devrait aller bien au-delà du fichier Readme classique. Après Daniele Procida je vous suggère d’inclure les éléments suivants dans votre documentation pour une expérience utilisateur inégalée:

Didacticiels

Un débutant adorera trouver un didacticiel dans ses documents. Les didacticiels expliquent aux utilisateurs comment mener à bien un projet à l'aide de votre logiciel, afin qu'ils puissent rapidement comprendre ce qu'ils peuvent en faire.

Les didacticiels sont des leçons qui entraînent le lecteur par la main. une série d'étapes pour mener à bien un projet quelconque. Ils sont ce dont votre projet a besoin pour montrer aux débutants qu’ils peuvent réaliser quelque chose avec. – Daniele Procida

Guides de procédures

Les guides de procédures aident les utilisateurs à résoudre des problèmes concrets à l'aide de votre logiciel. Procida les compare aux recettes en ce sens qu’il s’agit de directives que vous donnez aux utilisateurs pour qu’ils puissent atteindre un certain objectif. Contrairement aux tutoriels, qui s'adressent aux débutants, les guides d'utilisation supposent que les utilisateurs possèdent déjà des connaissances de base en fonctionnalités, outils et réalisation de tâches simples.

Guides de référence

Les guides de référence sont des références techniques des logiciels que vous utilisez. code – fonctions, API, etc. – et offre une description de base de l’utilisation du logiciel. Par exemple, vous trouverez une illustration sur la façon d'instancier une classe spécifique, d'appeler une méthode particulière, etc.

Les guides de référence sont des descriptions techniques de la machine et comment l'exploiter. . – Daniele Procida

Il s’agit du document que vous êtes susceptible de trouver dans la plupart des projets. Les développeurs ont tendance à être assez doués pour l'écrire car ils connaissent parfaitement leur code et son utilisation.

Explication

Les explications constituent une analyse approfondie d'un sujet particulier que vous jugez pertinent pour un sujet particulier. compréhension de niveau supérieur de votre logiciel. À propos des explications, Procida fait remarquer que –

Cette section de la documentation est rarement créée explicitement et que des extraits d’explications sont dispersés dans d’autres sections. Parfois, la section existe, mais porte un nom tel que Background ou Other notes et ne rend pas vraiment justice à la fonction.

Un sujet n'est pas défini par une tâche spécifique que vous souhaitez accomplir. , comme un guide pratique, ou ce que vous voulez que l’utilisateur apprenne, comme un tutoriel. Ce n’est pas défini par un élément de la machine, comme un matériau de référence. Il est défini par ce que vous considérez comme un domaine raisonnable à couvrir en même temps, de sorte que la répartition des sujets de discussion peut parfois être un peu arbitraire.

Ce sur quoi vous devez faire attention [19659004] Voyons quelques astuces utiles pour rendre vos documents conviviaux et pertinents.

Rendre vos documents découvrables

C'est une bonne idée de travailler à rendre la documentation de vos logiciels facile à trouver. Vous pouvez utiliser des techniques de référencement associées à des stratégies de marketing afin que le plus grand nombre possible d'utilisateurs puissent s'en procurer.

De plus, ce que vous mettez dans vos documents devrait être organisé dans une structure qui facilite la recherche d'informations spécifiques. Steve Konves vous recommande de structurer vos documents dans un arbre lié entre eux: à partir du nœud racine, qui doit être placé dans un emplacement évident à découvrir par tous les utilisateurs intéressés, tous les autres éléments sont facilement accessibles. Le fichier Lisez-moi du projet est un excellent nœud racine pour l'ensemble de l'arborescence.

De plus, si vous recevez des demandes d'aide de la part des utilisateurs de votre logiciel, vous pouvez écrire les réponses et les mettre à disposition dans une page FAQ facilement accessible. . Cela diminuera le temps que vous passerez à aider les utilisateurs, mais vous donnera également une idée plus précise du type d'informations dont les utilisateurs ont le plus souvent besoin, de sorte que vous puissiez les documenter en premier et les conserver à un endroit bien en vue dans vos documents.

Assurez-vous que vos documents sont à jour et exempts de bugs

Accéder facilement à la documentation de votre logiciel est un excellent moyen, mais si les utilisateurs découvrent que son contenu est obsolète ou si le code ou les instructions donnés en exemple conduisent à des résultats erronés, cela devient frustrant , Pour dire le moins. Steve Konves vous suggère néanmoins de garder vos documents proches du code, par exemple dans le contrôle de code source. Ainsi, lorsque les développeurs mettent à jour le code, ils remarquent la documentation, ce qui rend la mise à jour de la documentation beaucoup plus probable.

De plus, pour minimiser l'occurrence de bogues, testez minutieusement les instructions et les exemples de code fournis. dans vos docs.

Conseil supplémentaire et exemples populaires

Ne vous arrêtez pas à la documentation. Les articles de blog sont parfaits pour faire connaître votre logiciel et ses fonctionnalités à un large public d'utilisateurs potentiels. Utilisez votre blog pour clarifier ce que fait votre produit, proposer des didacticiels conviviaux, des astuces et conseils, des explications, des mises à jour, etc. Vous pouvez inclure votre blog dans un site Web autonome dédié à votre logiciel – éventuellement avec un forum – autour duquel une communauté forte peut se rassembler et se développer.

Un grand exemple de cette idée plus large de la documentation est selon moi mis en œuvre par GreenSock une plate-forme d'animation JS largement réussie, que je me trouve à utiliser beaucoup, notamment parce que son site Web propose des documents faciles à utiliser et bien structurés, un forum très utile, des billets de blog, des astuces rapides et bien plus encore.

React et Vue.js peut également être considéré comme un excellent exemple. Dès que vous accédez à leurs sites Web respectifs, la page d'accueil vous explique en quoi chaque bibliothèque est bonne dans un slogan rapide, puis explique plus en détail pourquoi cette bibliothèque peut être considérée comme un excellent choix pour votre projet. Les deux sites Web rendent la mise en route moins intimidante avec des introductions douces, des extraits illustratifs, des tâches courtes que les débutants peuvent accomplir avec des jeux de code, etc. Une fois que les utilisateurs ont acquis un peu de confiance avec le nouveau logiciel, ils peuvent facilement trouver les documents d'API plus techniques, ainsi que des pages. détaillant comment obtenir de l'aide, afficher des informations sur l'écosystème, proposer une section nouvelles ou un blog, etc.

Pour quitter la zone JS et accéder au domaine des bibliothèques d'interface utilisateur populaires dotées de sites Web formidables, je ne peux pas laisser de côté Bootstrap . Sur le site Web Bootstrap, vous trouverez tout de suite à quoi sert la bibliothèque, comment démarrer rapidement, des docs complets et bien structurés et un blog pour tenir les utilisateurs au courant des nouveautés.

Conclusion

Écrire une bonne documentation a ses défis, mais cela rapporte certainement cent fois si vous pensez à quel point il sera plus facile pour vos utilisateurs d’implémenter les fonctionnalités de votre logiciel. Cela contribue à la popularité de votre logiciel, ce qui le rend attrayant et donc ouvert à la possibilité de donner naissance à une communauté de développeurs prêts à investir leur temps à l’apprendre en profondeur et à contribuer à sa croissance, sa stabilité et sa durabilité. utilisation.

Maria Antonietta Perna est corédactrice du canal HTML / CSS de SitePoint et développeur web front-end. Elle aime bricoler avec les normes CSS rigoureuses et est curieuse d’apprendre des approches pédagogiques du code frontal. Lorsqu'elle ne code pas pour le Web ou n'écrit pas pour le Web, elle aime les livres de philosophie, les longues promenades et la bonne nourriture.