Outils pour Créer une Documentation de Site Web Drupal
Que vous soyez indépendant ou programmeur contractuel, nous faisons tous face au même problème lorsque nous commençons à travailler sur un projet existant pour un client : comment se familiariser rapidement et (si possible) sans douleur avec la structure et le code existants. Probablement chacun de nous au moins une fois dans sa carrière a demandé avec espoir : Avons-nous une documentation ici ?
Si vous ne pouvez pas l'expliquer simplement, vous ne le comprenez pas suffisamment bien. (Albert Einstein)
Importance de la documentation de projet
La documentation fait partie du produit, c'est son complément inestimable et un guide – pour le programmeur, le gestionnaire, le propriétaire du produit et l'utilisateur final. Une documentation bien structurée et bien rédigée est une situation gagnant-gagnant. D'une part, vous minimisez la portée des questions que le client vous posera, et d'autre part – vous facilitez la tâche aux personnes qui rejoindront votre équipe ou qui prendront en charge le support du système après vous. Par conséquent, avoir (et ce qui est particulièrement important) maintenir la documentation la plus à jour est un investissement et une démarche stratégique, notamment dans les grands projets.
Si ce n'est pas documenté, cela n'existe pas. (Sitepoint, Guide d'écriture de votre première documentation logicielle)
Types de documentation de projet
Au plus haut niveau de généralisation, nous pouvons diviser la documentation de projet en documentation système et documentation utilisateur final.
Le premier type de matériel intéressera particulièrement les développeurs, le second – le client et l'utilisateur final (l'utilisateur Internet). Cependant, comment gérer l'explication de toutes les complexités et spécificités d'un projet donné, comment mieux documenter les processus se déroulant dans le back-end, et comment dissiper les doutes des utilisateurs de manière visuelle et simple ? Un large éventail d'outils vient à la rescousse, avec leurs fonctionnalités qui vous aideront à répondre à ces questions, ainsi qu'à créer votre documentation de site web.
Documentation sous forme de livre
L'une des formes couramment utilisées pour collecter la documentation est la création de contenu hiérarchique avec des chapitres et des sous-sections – comme dans un livre, c'est-à-dire une version papier des instructions pour les utilisateurs qui accompagne chaque produit.
Il existe plusieurs outils pour créer une telle structure de contenu. Ils possèdent tous des éditeurs de texte intégrés qui vous permettent d'ajouter facilement un fragment de code, des listes, des tableaux et des pièces jointes multimédias.
Confluence
Après quelques étapes simples (surtout si vous utilisez déjà d'autres produits Atlassian), vous obtenez un site personnalisé avec la possibilité de créer plusieurs zones (par exemple, pour plusieurs versions de produit) dans lesquelles des pages avec des articles peuvent être créées. Vous disposez d'un tutoriel complet et de plusieurs dizaines de modèles de contenu. La création de votre "livre" est facilitée par la possibilité de glisser librement et de décider de l'ordre et de l'emplacement des sous-pages ajoutées, ainsi que par la possibilité de les taguer, de les aimer, de commenter et de les marquer. L'outil est visuellement clair et lisible. De plus, la version gratuite offre 2 Go d'espace à votre disposition, et vous pouvez inviter jusqu'à dix personnes à coopérer. Confluence mérite d'être essayé, surtout si vous conservez votre code dans le dépôt Bitbucket et que vous distribuez des tâches à l'aide de Jira Software.
GitHub Pages et GitLab Wiki
Si vous aimez garder votre documentation proche de votre code, la solution idéale est les fonctionnalités de wiki offertes par les sites d'hébergement créés à cet effet. Certes, vous n'avez pas de modèles d'articles à votre disposition ici, mais le contenu saisi est toujours à portée de main – juste à côté du dépôt, des tâches ou des processus de mise en œuvre de nouveaux codes. L'organisation du contenu est similaire à ce qui a été mentionné précédemment avec Confluence. Gitlab vous permet même d'importer la documentation existante de cet outil. Les articles individuels peuvent être regroupés en indiquant le chemin dans l'arborescence du répertoire de vos chapitres. Lors de l'ajout de contenu, vous disposez d'un éditeur simple qui prend en charge des formats tels que Markdown, Rdoc, AsciiDoc, reStructuredText ou Org, et le processus de publication lui-même est réalisé en ajoutant un autre package de code (message de commit). Github Pages propose également des habillages par défaut qui donneront un aspect professionnel à votre page de documentation.
Camunda Modeler et Process Street
Si le module Workflows est le centre autour duquel tourne le fonctionnement de l'ensemble du site, alors pour comprendre toutes les dépendances et processus se déroulant sur le site (par exemple, comment le processus de prêt, de demande de financement, de réservation d'une visite, etc. est effectué), des outils comme Camunda Modeler ou Process Street s'avéreront une aide inestimable. Ils sont utiles tant pour la planification des processus que pour leur documentation. Le but principal de ces outils est de soutenir la gestion des processus métier (BPM) et (dans le cas de Camunda) de créer des arbres de modèles de décision et de notation (DMN).
En bref, s'il existe des processus récurrents sur votre site web qui méritent d'être documentés, vous pouvez le faire avec ces outils. Vous serez en mesure de créer des documents contenant des procédures ou de lancer des processus pour vos collègues en quelques secondes. Process Street est utilisé lors de la mise en œuvre de nouvelles solutions ou de la publication de nouvelles versions du système.
Tandis que la direction sera ravie des capacités de Process Street, les développeurs et les analystes métiers seront plus enclins à utiliser Camunda Modeller. Le programme fonctionne avec tous les systèmes d'exploitation et fonctionne comme un cloud. Il vous permet de refléter avec précision tous les processus et les connexions entre les serveurs. Il existe également un emplacement désigné pour collecter toutes les informations nécessaires qu'un développeur peut avoir besoin : adresses des serveurs, format des requêtes envoyées et des réponses reçues, avec paramètres, etc. Le tout est très clair et intuitif.
Documentation comme du code
Il est temps de passer aux solutions qui réchauffent le cœur des programmeurs les plus fervents – la documentation dans le code ! Du point de vue d'un nouveau membre de l'équipe dans un grand projet pour un client, la documentation comme partie intégrante du code est la solution parfaite. La culture de la documentation technique telle que nous la comprenons aujourd'hui a été initiée en 2014 par les employés de Twitter qui ont franchi une étape au-delà du modèle communément accepté – un développeur écrit le code, laissez-le écrire aussi la documentation – et ont déclaré qu'ils devraient écrire la documentation comme le code. L'approche docs as code a dépassé toutes les attentes. Nous parlons ici d'écrire la documentation au même endroit que le code – en utilisant exactement le même processus de publication que lors de l'ajout de code : commit, pull request, build. Les commentaires dans le code ont déjà favorisé cette approche auparavant.
ReadMe.md!
Sûrement, tout le monde a déjà rencontré un fichier appelé README.md. Peut-être a-t-il été écrit comme un fichier texte brut ou dans l'un des formats de texte dits légers. Il contient des informations de base sur le projet, sur la manière de configurer sa version de développement localement, sur qui l'a créé et le maintient, etc.
Vous pouvez aller un peu plus loin, cependant, et créer toute la documentation du projet de cette façon. Pour ce faire, cependant, il vaut la peine d'utiliser l'un des formats disponibles, qui transforme la version simplifiée du texte en texte formaté facile à lire pour l'utilisateur. L'un des formats les plus couramment utilisés sont Markdown et reStructuredText.
Créez votre documentation
Et si vous pouviez automatiser tout le processus basé sur les commentaires sur le code existant, et en même temps – créer une sorte de livre de documentation qui se mettra à jour avec chaque changement dans le code ? Bien sûr, rien ne peut remplacer la contribution humaine à la création de la documentation de projet, mais la possibilité d'obtenir son cadre, son plan principal automatiquement, semble encourageante.
Il existe de nombreux générateurs de ce type, et parmi ceux-ci, les plus utiles pour les utilisateurs de Drupal seront évidemment ceux basés sur le code PHP. Ceux qui méritent d'être recommandés ici sont :
- ApiGen – crée une documentation API propre sur la base du code source PHP.
- Dexy – l'un des générateurs les plus polyvalents, il prend en charge plusieurs langages de programmation et formats d'entrée et de sortie.
- docgenerator – vous permet d'organiser la documentation sous forme de fichiers Markdown.
- DocumentUp – pour les propriétaires de code sur GitHub, il vous permet d'améliorer la documentation créée à l'aide du format Markdown.
- Doxygen – prend en charge de nombreux langages de programmation, génère la documentation en ligne (HTML) ou en tant que manuel en LateX ou autres formats de texte (PDF, MS Word).
- phpDocumentor – l'un des premiers de son genre, vous permet de créer des diagrammes de classes en UML, prend en charge la dernière version de PHP, offre un large éventail d'aides et possède de nombreuses années d'expérience.
- PhpDox n'est pas limité à la documentation API. Les informations collectées sont stockées dans les fichiers XML qui peuvent être librement modifiés puis générés en tant que fichiers HTML.
Utilisez Drupal pour la documentation de projet
Dans notre agence Drupal, nous avons décidé d'utiliser Drupal pour créer de la documentation pour l'usage interne de l'entreprise. La version de base d'un site Drupal est facile à configurer et est fournie avec des types de contenu par défaut qui suffisent pour commencer. Nous n'avons même pas besoin d'apprendre quoi que ce soit de nouveau – après tout, nous sommes des spécialistes de Drupal ! Dans notre cas, nous avons également activé le module "Book". Les pages ajoutées créent des collections liées les unes aux autres – comme dans le cas d'un livre réel.
La vue principale de la documentation se compose de deux parties : sur le côté gauche, il y a un bloc avec l'arborescence du contenu, sur le côté droit, le contenu du chapitre sélectionné est chargé. Chaque page est ajoutée comme un nœud distinct, nous utilisons le CKEditor par défaut pour créer/éditer le contenu. Il est amélioré avec un plug-in CodeSnippet supplémentaire. Nous avons ajouté nos couleurs d'entreprise à tout cela et... voilà ! Le contenu est modéré par à la fois – les développeurs et les personnes non techniques. Il stocke du contenu allant des questions typiques liées à RH au développement de projets locaux. Nos nouveaux employés reçoivent un référentiel de connaissances prêt à l'emploi sur la façon de naviguer dans toutes les questions de l'entreprise et comment démarrer le travail sur le projet assigné.
Résumé
Il existe de nombreux outils pour vous aider à créer et, plus important encore, à maintenir une documentation à jour. Le choix de ces outils dépend des spécificités de votre projet – sa taille, le nombre et le type de modules utilisés. Cela dépend aussi de savoir si le site est principalement statique ou basé sur des processus, qui créera et utilisera la documentation, si vous souhaitez la partager et de nombreux autres facteurs. Cependant, le fait que la documentation fasse partie du produit et ait une valeur économique – car elle permet de réduire les coûts (c'est-à-dire, le nombre d'heures nécessaires aux développeurs pour se familiariser avec tout) – restera vrai. Une bonne documentation aide également à attirer des clients (comme nous l'avons déjà cité – "si ce n'est pas documenté, cela n'existe pas" ;)) Allez-y donc !
