Un guide pour rédiger votre premier document logiciel

En tant que développeur, votre fierté et votre joie sont votre code. Il est lisible, il répond aux principes secs, il reflète les meilleures pratiques et le produit final est un excellent outil qui résout une sorte de problème pour ses utilisateurs cibles. Cependant, peu importe la quantité de travail que vous avez consacrée à votre code, si votre logiciel n'est pas livré sans documentation, ou si vous écrivez de la documentation après coup et le traitez avec peu d'importance, il est probable que les utilisateurs trouvent peu de joie de travailler avec lui, et finalement opter pour un produit différent et plus convivial.

Dans cet article, vous trouverez un certain nombre de principes directeurs pratiques pour vous mettre en fonction de la rédaction de votre première documentation logicielle.

Les plats clés

• Une bonne documentation logicielle est cruciale pour l'adoption et la compréhension des utilisateurs, servant d'outil de communication entre les développeurs et les utilisateurs. Il devrait inclure des tutoriels, des guides pratiques, des guides de référence et des explications, fournissant un guide complet des capacités du logiciel.
• Le public cible de la documentation doit être clairement identifié, car cela façonnera le contenu et le langage utilisés. Dans le contexte de ce guide, l'accent est mis sur la documentation pour les développeurs de familiarité variable avec le logiciel, plutôt que sur les manuels d'utilisateurs ou la documentation du projet.
• La documentation doit être facilement découvrable, bien structurée et régulièrement mise à jour. Il est recommandé de maintenir la documentation proche du code, dans le contrôle de la source, pour s'assurer qu'il reste pertinent et précis à mesure que les mises à jour de code se produisent. L'inclusion d'une page FAQ peut également aider à répondre aux requêtes utilisateur communes.
• Au-delà de la documentation traditionnelle, les articles de blog peuvent servir d'outil utile pour expliquer les fonctionnalités logicielles, fournir des tutoriels et partager des mises à jour. Cela peut favoriser une communauté autour du logiciel, contribuant à sa croissance et à sa réussite. Des exemples de bonnes pratiques de documentation peuvent être trouvés dans des plates-formes telles que Greensock, React et Vue.js.

Pourquoi la documentation est importante

En référence à votre logiciel, Mike Pope a un dicton approprié qui va comme ceci: s'il n'est pas documenté, il n'existe pas .

Pourquoi est-ce? Eh bien, juste pour prendre mon expérience personnelle à titre d'exemple, je parcourais le Web à la recherche de nouvelles bibliothèques d'animation JavaScript pour essayer et j'en ai rencontré une avec une description de ses fonctionnalités que j'ai vraiment aimé. Cependant, il n'y avait pas de documentation, pas même une section de démarrage, mais juste une page API à nu avec presque aucune explication ni exemples. Pensez-vous que j'ai fini par utiliser cette bibliothèque? Bien sûr, je ne l'ai pas fait. Je suis devenu tellement frustré par ça que je suis passé à quelque chose qui avait plus de sens pour moi.

à la question de Pourquoi les bonnes bibliothèques JavaScript échouent , Nicholos Zakas donne la réponse suivante:

Manque de documentation . Peu importe à quel point votre bibliothèque est merveilleuse et à quel point son design est intelligent, si vous êtes le seul à le comprendre, il ne fait aucun bien. La documentation signifie non seulement les références d'API autogenières, mais également les exemples annotés et les tutoriels approfondis. Vous avez besoin des trois pour vous assurer que votre bibliothèque peut être facilement adoptée.

Une autre raison importante pour laquelle vos documents logiciels sont essentiellement importants est qu'ils servent d'outil de communication entre votre moi actuel et votre moi futur, ainsi que entre votre moi actuel et d'autres développeurs qui pourraient finalement se retrouver à travailler sur votre logiciel. Même si vous écrivez du code lisible et commenté, cela ne signifie pas nécessairement que cela vous sera toujours clair dans six mois pourquoi vous avez écrit une fonction, ou tout autre élément de votre code d'ailleurs, comme vous l'avez fait.

La documentation

vous permet de transférer le code pourquoi derrière le code. De la même manière, les commentaires de code expliquent le pourquoi , et non le comment , la documentation sert le même objectif. - Guide du débutant pour écrire la documentation

sûrement, vous voulez que les gens utilisent votre code et puissent également pouvoir le mettre à jour et l'améliorer. Ce sont tous des facteurs contributifs à la croissance d'une communauté de soutien derrière votre produit, ce qui est important pour qu'il gagne la robustesse, la maturité et le succès.

Il sera très difficile d'accomplir tout cela si votre logiciel n'a pas d'excellents documents pour l'accompagner.

qui est la documentation logicielle pour

Lorsque vous écrivez quoi que ce soit, assurez-vous qu'il est clair dans votre esprit qui est votre public. 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 est susceptible d'avoir avec votre produit ou les conditions préalables à l'utilisation de votre produit. Ces informations sont cruciales pour la façon dont vous créez le contenu et la langue que vous utilisez.

Il existe deux types de documentation dans cet article:

1. manuels utilisateur. Par exemple, ma sœur pourrait décider d'utiliser WordPress pour publier son propre blog. Elle n'est pas un développeur, mais elle a entendu dire que les non-DEV peuvent mettre leur blog opérant en un rien de temps avec WordPress. Maintenant, elle aura besoin d'instructions sur la façon de télécharger et de configurer le logiciel sur son serveur, comment écrire, publier et mettre à jour ses publications, comment ajouter des images à un article, 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, bien que certains de ses contenus puissent être consacrés au fichier de réadme d'un projet. Pour continuer avec l'exemple WordPress, après avoir obtenu beaucoup de pratique avec WordPress, je pourrais décider que je voudrais ajouter une fonctionnalité au logiciel ou corriger un ou deux bogues. Dans ce cas, je devrai savoir des choses comme les modifications, les conventions et les meilleures pratiques, les politiques de contribution, comment participer à des discussions en équipe pertinentes pour la tâche à accomplir, etc.

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

Que inclure dans votre documentation

Une approche populaire est le développement de Readme, défendu par Tom Preston-Werner. Il consiste à écrire le document ReadMe avant même de commencer à écrire n'importe quel code. Ce document est une introduction à votre logiciel et comprend généralement:

• Une explication de ce que fait votre logiciel et quel problème il résout
• un exemple illustrant les circonstances dans lesquelles votre code serait normalement utilisé
• Liens vers le code et les bogues tracker
• FAQ et façons de demander le soutien
• Instructions sur la façon d'installer votre logiciel
• Informations sur la licence

Cependant, à mon avis, avoir une documentation solide qui peut vraiment aider les développeurs qui utilisent votre logiciel / bibliothèque devrait aller bien au-delà du fichier de réadme classique. Après Daniele Procida, je vous suggère d'inclure les éléments suivants dans votre matériel de documentation pour une excellente expérience utilisateur.

Tutoriels

Un débutant adorera trouver un tutoriel dans vos documents logiciels. Les tutoriels consistent à montrer aux utilisateurs comment terminer un projet à l'aide de votre logiciel, afin qu'ils puissent rapidement avoir une idée de ce qu'ils peuvent en faire.

Les tutoriels sont leçons qui emportent le lecteur par la main à travers une série d'étapes pour terminer un projet d'une certaine sorte. C'est ce dont votre projet a besoin pour montrer à un débutant qu'il peut réaliser quelque chose avec. - Daniele Procida

guides pratiques

Les guides pratiques aident les utilisateurs à résoudre une tâche réelle à l'aide de votre logiciel. Procida les compare aux recettes dans le sens où ils sont des instructions que vous donnez aux utilisateurs afin qu'ils puissent atteindre avec succès un certain objectif. Contrairement aux tutoriels, qui sont destinés aux débutants complets, les guides pratiques supposent que les utilisateurs possèdent déjà des connaissances de base des fonctionnalités, des outils et de la façon d'effectuer des tâches simples.

Guides de référence

Les guides de référence sont des références techniques du code de votre logiciel - fonctions, API, etc. - et offrent une description de base de la façon d'utiliser le logiciel. Par exemple, vous trouverez une illustration de la façon d'instancier une classe spécifique, comment appeler une méthode particulière, etc.

Les guides de référence sont

Descriptions techniques de la machine et comment la faire fonctionner. - Daniele Procida

Il s'agit du morceau de documentation que vous trouverez probablement dans la plupart des projets. Les développeurs ont tendance à être assez bons pour l'écrire car ils savent tout sur leur code et comment l'utiliser.

Explication

Les explications sont une plongée profonde sur ou une discussion sur un sujet particulier que vous pensez être pertinent pour une compréhension de votre logiciel. À propos des explications, Procida souligne que -

Cette section de documentation est rarement créée explicitement, et à la place, des extraits d'explication sont dispersés entre autres sections. Parfois, la section existe, mais a un nom tel que

d'arrière-plan ou d'autres 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 réaliser, comme un guide pratiques, ou ce que vous voulez que l'utilisateur apprenne, comme un tutoriel. Il n'est pas défini par un morceau de machine, comme le matériau de référence. Il est défini par ce qui

vous pense que c'est un domaine raisonnable à essayer de couvrir en même temps, donc la division des sujets de discussion peut parfois être un peu arbitraire.

des choses auxquelles vous devez faire attention

passons par quelques conseils utiles sur la création de vos documents conviviaux et pertinents.

rendre vos documents découvrables

C'est une bonne idée de faire du travail pour rendre la documentation logicielle facile à trouver. Vous pouvez utiliser certaines techniques de référencement avec certaines stratégies de marketing afin que le plus de nombreux utilisateurs possible puissent la saisir.

De plus, ce que vous mettez dans vos documents doit être organisé en une structure qui rend la recherche d'informations spécifiques un jeu d'enfant. Steve Konves vous recommande de structurer vos documents dans un arbre lié individuellement: à partir du nœud racine, qui doit être placé dans un emplacement évident pour chaque utilisateur intéressé à découvrir, tous les autres éléments peuvent être facilement accessibles. Le fichier ReadMe du projet se prête très bien comme un excellent nœud racine pour l'ensemble de l'arborescence.

De plus, si vous recevez des demandes d'aide aux utilisateurs de votre logiciel, vous pouvez écrire les réponses et les rendre disponibles dans une page FAQ facilement accessible. Cela diminuera le temps que vous passerez à aider les utilisateurs, mais cela vous donnera également une idée plus claire du type d'informations dont les utilisateurs ont besoin le plus souvent afin que vous puissiez les documenter d'abord et les garder dans un endroit de premier plan dans vos documents.

Assurez-vous que vos documents sont à jour et sans bugs

Accéder facilement à votre documentation logicielle est excellente, mais si les utilisateurs découvrent que son contenu est obsolète ou que l'exemple de code ou d'instructions conduisent à des résultats de buggy, cela devient frustrant, pour le moins. Pourtant, Steve Konves suggère de garder vos documents près du code - par exemple, dans le contrôle de la source. De cette façon, lorsque les développeurs mettent à jour le code, ils remarqueront le matériel de documentation, ce qui fait de la mise à jour des documents un événement beaucoup plus probable.

Aussi, pour minimiser la survenue de bogues, testez soigneusement les instructions et les échantillons de code que vous fournissez dans vos documents.

Astuce supplémentaire et quelques exemples populaires

Ne vous arrêtez pas à la documentation. Les articles de blog sont idéaux pour créer votre logiciel et ses fonctionnalités connues d'un large public d'utilisateurs potentiels. Utilisez votre blog pour offrir des clarifications sur ce que fait votre produit, livrer des tutoriels, des conseils et des astuces conviviaux, des promenades, expliquer les mises à jour, etc. Vous pouvez inclure votre blog dans un site Web autonome dédié à votre logiciel - peut-être avec un Forum - autour de laquelle une communauté forte peut se rassembler et se développer.

Un excellent exemple de cette idée plus large de la documentation à mon avis est implémentée par Greensock, une plate-forme d'animation JS largement réussie, que je me retrouve à utiliser beaucoup, notamment parce que son site Web rend disponible facile à utiliser et bien Docs structurés, un forum super utile, des articles de blog, des conseils rapides et bien plus encore.

react et vue.js peuvent également être comptés comme d'exemples d'exemples. Dès que vous accédez à leurs sites Web respectifs, la page d'accueil vous indique pour quoi chaque bibliothèque est bonne dans un slogan rapide, puis explique plus de détails sur les raisons pour lesquelles la bibliothèque peut être considérée comme un excellent choix pour votre projet. Les deux sites Web rendent le démarrage moins intimidant en utilisant des introductions douces, des extraits illustratifs, des tâches courtes que les débutants peuvent accomplir en utilisant des terrains de jeux de code, etc. Une fois que les utilisateurs ont gagné un peu de confiance avec le nouveau logiciel, ils peuvent trouver les documents API les plus techniques facilement, plus les pages en plus Détaillant comment obtenir de l'aide, affichant des informations sur l'écosystème, offrant une section de nouvelles ou de blog, etc.

Pour quitter la zone JS et entrer dans le domaine des bibliothèques d'interface utilisateur populaires avec de grands sites Web, je ne peux pas laisser de côté bootstrap. Sur le site Bootstrap, vous trouverez immédiatement à quoi la bibliothèque est bonne et comment démarrer rapidement, ainsi que des documents complets et bien structurés et un blog pour tenir les utilisateurs à jour sur ce qui est nouveau.

Conclusion

La rédaction de la bonne documentation a ses défis, mais elle est certainement payante cent fois si vous pensez à quel point il sera plus facile pour vos utilisateurs de mettre en œuvre les capacités de votre logiciel. Cela contribue à son tour à la popularité de votre logiciel, ce qui le rend attrayant et donc ouvert à la possibilité de donner naissance à une communauté de développeurs qui sont prêts à investir leur temps pour l'apprendre profondément et à contribuer à sa croissance, à sa stabilité et à son long terme utilisation.

Questions fréquemment posées (FAQ) sur la rédaction de la documentation des logiciels

Quels sont les éléments clés à considérer lors de la rédaction de la documentation logicielle?

Lors de la rédaction de la documentation logicielle, il est crucial de considérer le public cible, le but du document et le type de documentation en cours de rédaction. La langue utilisée doit être claire, concise et facile à comprendre. Le document doit être bien structuré, avec un flux logique d'informations. Il est également important d'inclure des visuels tels que des diagrammes ou des captures d'écran si nécessaire pour aider à la compréhension. Enfin, assurez-vous toujours que le document est en détail examiné et modifié pour la précision et la clarté.

Comment puis-je rendre ma documentation logicielle conviviale? et un langage clair. Évitez autant que possible le jargon et les termes techniques. Si vous devez les utiliser, assurez-vous de fournir des définitions claires. Organisez votre contenu logiquement et utilisez des en-têtes et des sous-titres pour faciliter la navigation. Incluez une table des matières et un index pour des documents plus longs. Utilisez des visuels comme des diagrammes, des captures d'écran et des vidéos pour illustrer des concepts complexes.

Quels sont les différents types de documentation logicielle?

Il existe plusieurs types de documentation logicielle, y compris la documentation du système, la documentation utilisateur, et documentation technique. La documentation système donne un aperçu du système logiciel, y compris son architecture et son flux de données. La documentation utilisateur fournit des instructions sur la façon d'utiliser le logiciel et comprend les manuels d'utilisation et les guides d'aide. La documentation technique est destinée aux développeurs et comprend des commentaires de code, de la documentation de l'API et des guides de développement.

À quelle fréquence la documentation logicielle doit-elle être mise à jour?

La documentation logicielle doit être mise à jour chaque fois qu'il y a des modifications importantes dans les modifications de la logiciel. Cela peut être dû à des nouvelles fonctionnalités ajoutées, à la modification des fonctionnalités existantes ou à des bogues. C'est également une bonne idée de revoir périodiquement la documentation pour s'assurer qu'elle est toujours exacte et pertinente.

Quels outils puis-je utiliser pour écrire la documentation logicielle?

Il existe de nombreux outils disponibles pour rédiger une documentation logicielle, y compris les traitements de texte, les générateurs de documentation et les outils de documentation spécialisés. Certaines options populaires incluent Microsoft Word, Google Docs, Doxygen et Sphinx. Le choix de l'outil dépend de vos besoins spécifiques et de la complexité du logiciel.

Comment puis-je assurer la qualité de ma documentation logicielle?

pour garantir la qualité de la documentation de votre logiciel, révisez toujours et modifiez votre travail à fond. Envisagez d'avoir un collègue ou un rédacteur en chef professionnel examiner votre document. Utilisez un style et un format cohérents tout au long du document. Assurez-vous que les informations sont exactes, à jour et pertinentes. Enfin, envisagez d'obtenir des commentaires des utilisateurs pour identifier les domaines d'amélioration.

Quel est le rôle des visuels dans la documentation logicielle?

Les visuels jouent un rôle crucial dans la documentation logicielle. Ils peuvent aider à illustrer des concepts complexes, ce qui les rend plus faciles à comprendre. Ils peuvent également rompre de grands blocs de texte, ce qui rend le document plus lisible. Les exemples de visuels comprennent des diagrammes, des captures d'écran, des organigrammes et des vidéos.

Comment puis-je rendre ma documentation logicielle plus attrayante?

Pour rendre la documentation logicielle plus engageante, utiliser un ton conversationnel et une voix active . Brisez les grands blocs de texte avec des visuels et des puces. Utilisez des exemples et des études de cas pour illustrer les concepts. Incluez des éléments interactifs comme les quiz ou les exercices le cas échéant.

Quelle est l'importance de la cohérence dans la documentation logicielle?

La cohérence est importante dans la documentation logicielle car elle facilite le document et la compréhension. Il donne également au document un aspect professionnel. La cohérence s'applique à la langue, au style, au format et aux visuels.

Comment puis-je améliorer mes compétences en écriture de la documentation logicielle?

pour améliorer vos compétences en écriture de la documentation logicielle, pratiquez l'écriture régulièrement. Lisez d'autres documents logiciels pour en apprendre. Suivre des cours ou des ateliers sur l'écriture technique. Recherchez des commentaires sur votre travail et soyez ouvert aux critiques. Restez à jour avec les dernières tendances et les meilleures pratiques en matière de documentation logicielle.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!