18 Outils de documentation logicielle qui font le travail difficile pour vous

🟢 Matériel bonus : Liste de contrôle du flux de travail Git pour simplifier &rationaliser la gestion des versions

Sans documentation, un logiciel n’est qu’une boîte noire. Et les boîtes noires ne sont pas du tout aussi utiles qu’elles pourraient l’être parce que leur fonctionnement interne est caché à ceux qui en ont besoin au grand jour.

La documentation logicielle transforme votre logiciel en une boîte de verre en expliquant aux utilisateurs et aux développeurs comment il fonctionne ou est utilisé.

Vous avez probablement déjà vu de la documentation, mais si vous avez besoin d’un rafraîchissement, voici un exemple tiré de l’API de Slack :

Comme vous pouvez le voir, Slack explique tout ce qui concerne son API de manière atrocement détaillée. Toutes les pages connexes sont liées, il y a une barre latérale avec des sujets faciles d’accès, et des captures d’écran de ce que l’utilisateur peut s’attendre à voir.

Pour expliquer cela plus en détail, nous couvrirons les sujets suivants dans ce post de Process Street :

• Qu’est-ce que la documentation logicielle ?
• Options d’hébergement de documentation logicielle
• Outils de rédaction pour la documentation logicielle
• Mots finaux sur la documentation logicielle

Démarrons.

Qu’est-ce que la documentation logicielle ?

« La documentation en génie logiciel est le terme générique qui englobe tous les documents écrits et les matériaux traitant du développement et de l’utilisation d’un produit logiciel » – Prototype.io, Software Documentation Types and Best Practices

Tous les morceaux de logiciel devraient avoir une certaine forme de documentation qui explique, en détail, ce qu’est le produit, comment il fonctionne et pourquoi il fonctionne de cette façon.

« Si ce n’est pas documenté, ça n’existe pas » – Sitepoint, Guide de rédaction de votre première documentation logicielle

En tant que développeur, votre objectif principal est d’écrire le meilleur code possible. Vous voulez que votre code soit le meilleur de sa catégorie, facile à lire, facile à utiliser, et vous voulez que de grandes choses se produisent à la suite de celui-ci. N’est-ce pas ?

Mais sans documenter ce que vous avez fait et pourquoi vous l’avez fait :

• Personne d’autre que vous ne peut utiliser votre code

Sans documentation, personne ne comprendra ce que vous avez fait et pourquoi vous l’avez fait. Il sera incroyablement difficile, voire impossible, pour quelqu’un d’autre de reprendre votre code et de travailler dessus. Ils pourraient même le mettre au rebut et recommencer, car, dans certains cas, ce serait plus rapide que d’essayer de comprendre ce que vous avez fait et pourquoi.

• Vous ne pouvez pas le mettre à jour ou l’améliorer

Pouvez-vous vous rappeler ce que vous avez mangé pour le dîner le samedi, il y a trois mois ? À moins que vous ne soyez une véritable créature d’habitudes, il y a de fortes chances que vous ne puissiez pas. Il est donc juste de dire que vous ne vous souviendrez probablement pas du code que vous avez écrit, deux, trois, quatre mois après l’avoir fait. Si vous ne pouvez pas vous souvenir des raisons derrière vos décisions de codage, alors vous aurez du mal à être capable de le mettre à jour ou de l’améliorer.

Malgré cela, la documentation logicielle est souvent une tâche qui est précipitée, mal faite, privée de priorité ou totalement oubliée.

Avant de commencer à parler des outils que vous pouvez utiliser pour écrire la documentation logicielle, nous devons penser à un moyen de s’assurer que la tâche est faite en premier lieu.

C’est là que Process Street peut aider.

Process Street est un logiciel de gestion des processus métier (BPM) qui peut être utilisé pour créer, gérer et suivre des processus.

Plus sur ce qu’est Process Street plus tard, pour l’instant, laissez-moi vous montrer comment vous pouvez l’utiliser comme un outil pour vous aider à intégrer la documentation logicielle dans chaque projet de développement logiciel sur lequel vous travaillez.

Vous trouverez ci-dessous un exemple de modèle de processus de déploiement de logiciels préétabli. Ce modèle a été créé pour aider les ingénieurs logiciels et les programmeurs à déployer leurs logiciels de la meilleure façon possible.

Cliquez ici pour accéder au processus de déploiement de logiciels !

Pour obtenir ce modèle, connectez-vous et ajoutez-le à votre tableau de bord, ou inscrivez-vous à un essai gratuit.

Ce modèle est un parfait exemple de processus que vous pouvez suivre chaque fois que vous voulez déployer un nouveau morceau de code ou une mise à jour.

Il comporte des étapes claires qui vous guideront tout au long du processus de déploiement, de la configuration d’un environnement de mise en scène à la mise en ligne de vos modifications. Ces étapes vous permettront de vous assurer que rien ne sera oublié et que l’ensemble du processus se déroulera en douceur à chaque fois.

Nous avons conçu ce modèle pour qu’il soit utilisé comme un guide pour vous aider à créer un processus de déploiement qui fonctionne pour vous. Chaque entreprise est différente, chaque projet logiciel est différent, et chaque processus de déploiement est différent.

Vous pouvez modifier ce processus et y ajouter les tâches qui sont pertinentes pour vous, votre entreprise et votre projet.

Ce qui me ramène à la documentation logicielle ; vous pourriez ajouter la  » documentation logicielle  » comme une tâche. De cette façon, toute personne travaillant dans le processus de déploiement du logiciel sera rappelée et encouragée à compléter ceci, comme faisant partie du processus.

J’ai quelques autres modèles de processus prémâchés qui pourraient vous être utiles, que je vais inclure à la fin de ce post.

Avant d’en arriver là, voyons où vous pouvez stocker votre documentation logicielle.

Options d’hébergement de la documentation logicielle

Il n’est pas bon d’avoir juste un tas de fichiers texte vivant sur votre ordinateur. Ils doivent être accessibles par les développeurs et les utilisateurs, ce que vous allez très probablement faire en hébergeant les docs sur Internet puisque ce n’est pas les années 1980.

Process Street (pour un usage interne)

Pour former les nouveaux développeurs et garder votre documentation vivante au même endroit, Process Street est un choix solide pour la documentation logicielle.

D’abord, vous pourriez créer un processus pour écrire votre documentation, afin de vous assurer que vous capturez tous les bons détails et que vous la rendez aussi utile que possible.

En utilisant les fonctionnalités faciles à utiliser suivantes, vous pouvez ensuite rédiger et stocker votre documentation en un seul endroit :

• Widgets d’image
• Widgets de texte
• Widgets de vidéo
• Widgets de fichier
• Sous-tâches
• Widgets d’e-mail
• Widgets d’embarquement

Stocker votre documentation au sein de Process Street signifie qu’elle est accessible à tous dans l’entreprise. Vous pouvez la partager avec d’autres personnes, l’envoyer pour approbation, définir des rappels pour la réviser et la mettre à jour facilement.

Check it out :

Si cela peut être documenté, cela peut être documenté dans Process Street.

Signez-vous pour un essai gratuit ici et essayez-le.

Read The Docs

Il est remarquable que Read The Docs soit gratuit quand on voit tout ce qu’il peut faire. Comme pour GitHub, vous pouvez créer autant de matériel open-source que vous le souhaitez qui est ouvertement indexé sur le site, mais cela va vous coûter si vous voulez rendre les docs privés et internes à votre entreprise. Pour nos besoins, il est probable que vous serez d’accord pour que les docs soient facilement disponibles pour les utilisateurs sur le web.

La raison pour laquelle Read The Docs est si bon est que vous pouvez importer sans effort la documentation de n’importe quel système de contrôle de version, y compris Git, Mercurial, Subversion et Bazaar. Il prend également en charge les webhooks afin que les docs soient construits automatiquement chaque fois que vous commettez du code.

Voyez leur guide de démarrage pour avoir une idée de la façon dont il fonctionne et comment vos docs se comporteraient lorsqu’ils y sont hébergés.

GitHub (& Pages GitHub)

Si vous utilisez GitHub pour gérer le contrôle de version de votre logiciel, vous avez, au strict minimum, un fichier README.MD dans le dépôt. Pour utiliser GitHub pour documenter votre logiciel, comme des millions d’autres l’ont fait dans le passé, il suffit de remplir ce README avec du markdown.

Un excellent exemple est le dépôt t de sferik, dont la capture d’écran est ici :

Si vous voulez plus qu’une simple feuille de texte formaté, vous pouvez profiter de l’outil Pages de GitHub (vous obtenez une page web gratuite + hébergement avec chaque compte GitHub, et vous pouvez même y router un domaine personnalisé). Pages a même de superbes thèmes par défaut qui donnent à votre documentation un aspect professionnel.

Au-dessus se trouve la documentation atom.io pour Electron hébergée sur GitHub. C’est un choix intelligent car elle fonctionne automatiquement avec le contrôle de version de GitHub, tout comme le reste de votre logiciel. Voir le dépôt du site ici.

Dropbox Paper (pour un usage interne)

Pour un usage interne de documentation logicielle, Dropbox Paper est un excellent choix. Comme son prédécesseur Hackpad, vous pouvez l’utiliser pour créer un wiki privé pour les employés. Vous pouvez relier des documents entre eux, insérer des blocs de code, des images et des sauts de page, comme vous l’exigeriez de n’importe quel outil de documentation.

Comme vous pouvez le voir dans les commentaires à droite, vous pouvez également l’utiliser pour passer par des processus d’approbation et collaborer à la création de la documentation. Dans l’ensemble, c’est un excellent outil pour développer et créer de la documentation en interne, peut-être dans l’optique de la rendre publique plus tard, ou simplement la garder pour un usage interne.

Atlassian REST API Browser (pour l’utilisation des API)

Le REST API Browser (RAB) d’Atlassian est inclus dans les instances de JIRA Server, Confluence Server et Stash par défaut. Il est construit pour découvrir les API disponibles pour une utilisation dans les environnements JIRA/Confluence, et aussi un endroit pour héberger votre documentation. Si, bien sûr, votre API correspond au projet.

Documentez votre API à l’aide de cet outil pour donner plus d’exposition à votre API compatible avec JIRA/Confluence. Vérifiez ici pour la documentation d’Atlassian sur la façon de le faire.

Tettra (pour usage interne)

Tettra est une sorte de logiciel de base de connaissances où vous pouvez documenter votre développement, ou n’importe quoi du tout.

Nous utilisons Tettra en interne à Process Street pour un tas de cas d’utilisation. Au jour le jour, j’utilise Tettra pour avoir un endroit unique où tous mes processus sont documentés afin que je n’oublie jamais comment l’un se rapporte à l’autre ou comment les diverses automations que nous avons construites ont été configurées.

Tettra est génial si vous cherchez à créer une sorte de bibliothèque. Cela signifie qu’il est brillant pour la documentation du logiciel ou même simplement comme un wiki interne pour votre entreprise.

Du fait que Tettra est spécifiquement conçu pour la gestion des connaissances, il est livré avec une foule d’autres fonctionnalités de soutien aussi. Par exemple, il peut faire des suggestions sur le contenu supplémentaire ou les sections que vous pourriez vouloir ajouter pour donner une image plus complète de votre org et comment les choses s’emboîtent.

Vous pouvez voir une petite vidéo ici pour savoir comment une équipe de dev pourrait regarder pour utiliser Tettra : Comment les équipes d’ingénierie de produit & utilisent Tettra.

Ou, vous pouvez aller ici pour lire comment nous utilisons Tettra aux côtés de Process Street : Automatisation des flux de travail et des listes de contrôle : Étude de cas de Process Street.

Check it out!

Apiaire (pour l’utilisation des API)

En plus d’être un lieu où vivent les abeilles, Apiaire est un hôte dédié à la documentation des API. Écrivez en markdown, ajoutez des appels d’API fictifs et Apiary rassemble cela en quelque chose comme ce que vous voyez ci-dessous :

Tout le monde peut tester l’API sans avoir à entrer dans l’application ou à programmer réellement un appel, ce qui en fait un moyen super accessible de partager votre API, de la documenter en profondeur et de vous vanter de ce qu’elle peut faire.

Nous avons discuté de l’endroit où stocker votre documentation logicielle, il est maintenant temps d’examiner comment l’écrire.

Outils d’écriture pour la documentation logicielle

La documentation logicielle est souvent écrite en markdown pour permettre les hyperliens et le formatage tout en la gardant en texte brut afin qu’elle puisse vivre aux côtés des fichiers de code dans le contrôle de version. Cela signifie que beaucoup de mes choix d’outils d’écriture sont des éditeurs markdown simples qui rendent l’expérience d’écriture agréable. En outre, il y a aussi quelques solutions non markdown très efficaces jetées là.

MarkdownPad (Windows)

Avec une version gratuite et premium – toutes deux avec une tonne de fonctionnalités intéressantes – MarkdownPad est l’éditeur markdown le plus populaire pour Windows. Il est optimisé pour les billets de blog, les sites Web, les articles, les README et, bien sûr, la documentation logicielle.

Vous pouvez obtenir MarkdownPad gratuitement, ou obtenir la version premium pour 14,95 $.

iA Writer (Mac)

iA Writer est un éditeur markdown simple et beau avec une fonctionnalité de bibliothèque signifiant que vous pouvez facilement faire référence à d’autres documents dans la barre latérale. Il manque des liens internes entre les documents comme vous vous attendez à ce qu’il y en ait dans les docs de logiciels, mais vous pouvez toujours faire un passage sur ceux-ci quand il est dans sa forme finale (c’est-à-dire, s’il va finir sur Internet dans un site).

Si vous écrivez toute votre documentation dans une page brisée, vous pouvez utiliser des ancres de saut de page pour aider les utilisateurs à naviguer.

iA Writer coûte 9,99 $ sur le Mac App Store.

ProProfs Knowledge Base

Profs Knowledge Base est un petit outil fantastique pour toutes les étapes de la création de documents ; de la rédaction et de l’édition, à la personnalisation, à la définition de flux de travail et à la publication. Vous pouvez ajouter du multimédia, importer du contenu existant à partir de documents word, PDF ou PPT, enregistrer plusieurs versions du document et les restaurer si nécessaire.

Mais la véritable beauté de cet outil réside dans sa facilité d’utilisation. Tout le monde peut l’utiliser pour créer de la documentation logicielle. Que vous documentez des logiciels depuis des années ou que vous n’ayez commencé que récemment, c’est un outil incroyablement simple et facile à utiliser.

ProProfs est gratuit à utiliser, ou vous pouvez passer au forfait premium qui est de 112 $ par mois.

SimpleMDE (navigateur)

Bien que vous puissiez techniquement écrire markdown dans n’importe quel éditeur de texte parce que c’est une façon de formater du texte brut, pas strictement un « outil », il ne vous surprendra pas que ce soit également possible dans votre navigateur ! SimpleMDE est à la fois un éditeur markdown fonctionnel construit sur JavaScript et un projet open-source pour apprendre et adapter pour votre propre usage, si nécessaire.

SimpleMDE est 100% gratuit ! Obtenez la source sur GitHub ici.

Éditeurs reStructuredText

Markdown est l’un des deux langages les plus utilisés pour écrire de la documentation logicielle, mais il y en a un autre que nous n’avons pas examiné jusqu’à présent, et c’est reStructuredText. Il est très similaire à markdown, mais vaut la peine d’être appris à des fins de documentation logicielle.

Docutils, le créateur de reStructuredText, a mis en place une liste d’éditeurs reStructuredText ici, qui comprend :

L’intérêt de reStructuredText est qu’il est facile de convertir entre différents formats, notamment du texte brut vers un site web statique. Voir plus d’infos ici.

Outils pour générer automatiquement de la documentation à partir du code source

Il n’y a rien de tel que la touche humaine quand il s’agit de documentation (c’est clair dans les docs de Slack et Giphy, pour en nommer quelques-uns). Cependant, comme point de départ (surtout pour les énormes bibliothèques sources), il est préférable de générer la documentation squelettique automatiquement. Ce travail en analysant les fonctions et les commentaires de la source, et il y a quelques options différentes selon la langue :

Avant de vous lancer et de vous fier uniquement à la génération automatique, je vous suggère de lire ce fil de discussion StackExchange qui pèse le pour et le contre.

Mots finaux sur la documentation logicielle

Il y a beaucoup de solutions fantaisistes, de solutions rapides et d’outils qui sont (très honnêtement) presque identiques. Ce qui compte, en fin de compte, c’est que

Ce qui compte le plus, en fin de compte, c’est que :

a) vous écrivez une documentation logicielle pour chaque logiciel que vous construisez
b) vous l’écrivez de manière exhaustive et l’hébergez quelque part où l’utilisateur peut y accéder

J’ai mentionné plus tôt que j’avais quelques modèles de processus de développement supplémentaires que vous pourriez avoir envie de consulter ?

Eh bien, les voici…

Modèles de processus de développement Process Street

Avant de vous donner ces modèles, laissez-moi vous expliquer un peu plus ce qu’est Process Street.

On sait donc que Process Street, ce sont des listes de contrôle superpuissantes. C’est un logiciel qui va vous aider à créer et à gérer des processus.

Mais attendez, il y a plus que ça dans Process Street !

Voyez cette vidéo d’introduction pour découvrir ce que je veux dire :

Donc, vous voyez, non seulement vous pouvez créer un modèle de processus de développement et exécuter des listes de contrôle individuelles à partir de celui-ci chaque fois que vous avez besoin de compléter le processus de développement, mais vous pouvez le personnaliser en utilisant ces fonctionnalités supplémentaires

• Arrêter les tâches
• Dates d’échéance dynamiques
• Autorisations de tâches
• Logique conditionnelle
• Tâches d’approbation
• Embed widget
• Attributions de rôles

Attribuer des tâches, obtenir l’approbation, appliquer un ordre dans lequel les tâches sont accomplies, et vous pouvez connecter le processus à des milliers d’apps via Zapier, des webhooks ou une intégration API.

Regardez ce webinaire sur nos nouvelles fonctionnalités et voyez comment vous pouvez en tirer le meilleur parti :

Avec tout cela en tête, jetez un coup d’œil aux modèles préétablis ci-dessous :

Liste de contrôle de l’audit de sécurité du réseau

Ce modèle peut être utilisé par un gestionnaire de risques ou un professionnel de l’informatique équivalent pour évaluer un réseau à la recherche de vulnérabilités de sécurité.

Cliquez ici pour accéder à la liste de contrôle de l’audit de sécurité du réseau !

Liste de contrôle de la maintenance mensuelle d’un site Web

Utilisez cette liste de contrôle de la maintenance mensuelle d’un site Web pour optimiser la vitesse de chargement de votre site, rechercher des vulnérabilités et examiner votre visibilité dans les moteurs de recherche.

Cliquez ici pour accéder à la liste de contrôle de la maintenance mensuelle d’un site Web !

Tutoriel sur les tests de logiciels

Ce processus peut être utilisé pour gérer l’ensemble d’un projet de développement de logiciels du début à la fin, y compris la conception, la gestion des clients, mais aussi les vérifications après le lancement.

Cliquez ici pour accéder au tutoriel sur les tests logiciels !

Et voilà, vous l’avez.

Vous êtes maintenant libre d’utiliser ce qui vous facilite la vie. J’espère que vous trouverez votre nouvel outil préféré dans cette liste.