Après avoir acheté avec succès le logiciel de documentation, Dr.Explain, j’ai commencé à créer des fichiers d’aide pour tous mes projets, y compris ClassExplorer – “Guide du développeur”. Et puis j’ai soudain pensé : mon nouvel outil n’a-t-il pas remplacé le programme en cours de création pour moi ? Mon nouvel assistant vat-il se transformer en project killer ?
Dr.Explain vs ClassExplorer
De toutes les fonctionnalités du programme Dr.Explain, dans cet article, nous n’en analyserons qu’une seule – la création d’une base de connaissances, car c’est ainsi que se positionne le projet “Developer’s Reference” ou ClassExplorer.
Lors de la création d’un document dans Dr.Explain, vous pouvez choisir un modèle, ce qui peut vous faire gagner du temps et garantir l’exhaustivité de la description. Cela est particulièrement vrai lors de la maintenance de la documentation conformément à ГОСТ*. Un bon bonus du programme est le support intégré pour ГОСТ 34, qui spécifie les règles de base pour la préparation de la documentation du logiciel. Mais dans notre cas, ce n’est pas nécessaire, cliquez sur le bouton “Créer un projet local” (1).
*ГОСТ – est une norme d’État acceptable en URSS et en Russie, qui comprend les exigences de l’État concernant la qualité du produit, ses dimensions géométriques, les écarts par rapport à la norme, etc.
La form principale
L’espace de travail Dr.Explain est divisé en deux parties : à gauche se trouve une arborescence de sections (pages), au milieu se trouve un éditeur WYSIWYG, dont les fonctionnalités sont comparables au composant TdbRichEdit, qui est disponible pour les développeurs utilisant My Visual Database.
L’espace de travail ClassExplorer est organisé différemment : une barre d’outils minimaliste avec une barre de recherche, et en dessous se trouvent plusieurs onglets contenant des listes arborescentes ou linéaires par catégorie de page. Et pour afficher la page elle-même, vous devrez utiliser la recherche ou cliquer sur le bouton pour ouvrir l’exemple. Et pour modifier les données, vous devrez utiliser les boutons de la barre d’outils et les formulaires d’édition.
Arborescence des pages
Cela vaut la peine de regarder de plus près l’arborescence Dr.Explain. A première vue, un arbre est comme un arbre. Un seul, mais bon (c). En plus des pages utilisateurs, il contient plusieurs pages de service :
- Page du document (page acine)
- Page de garde
- Table des matières
La page de garde est l’élément généralement utilisé lors de la création d’un fichier d’aide – lorsque vous ouvrez un fichier sans spécifier de section, c’est la page de démarrage qui s’ouvre. Dans d’autres formats de sortie, il peut s’agir de la couverture du document. Mais pour chaque page, vous pouvez éventuellement configurer la nécessité d’exporter vers un format particulier :
La table des matières est un élément très utile lors de la création d’une documentation imprimée. Dr.Explain crée la table des matières automatiquement, sans nécessiter d’étapes supplémentaires pour mettre à jour la table des matières après avoir modifié le contenu. Dans le même temps, il est possible de personnaliser à la fois l’apparence et la profondeur de la construction de l’arborescence de la table des matières. En tant qu’auteur de plusieurs guides et tutoriels, j’ai apprécié cette opportunité
Page des Documents affiche des statistiques et contient des outils pour exporter des données (dans notre cas, pour créer un système d’information) dans différents formats.
Les statistiques disponibles sont un élément important de la planification de la production. Et c'est un point très important d'une approche professionnelle de la documentation: lors de la création d'une structure de document, vous créez (ou corrigez) simultanément un plan de travail, et l'état de préparation est affiché par un indicateur graphique spécial. Cela est possible grâce au fait que chaque section de l'arbre a un état de préparation spécial avec un code couleur.
Le chemin vers les données exportées est également affiché ici, qui est mémorisé après l’opération d’exportation – à mon avis une solution d’interface très agréable.
L’édition de l’arborescence de Dr.Explain est aussi pratique que possible, car il existe plusieurs options alternatives pour cela : boutons de la barre d’outils, raccourcis clavier et glisser avec la souris.
L’arborescence de ClassExplorer semblent plus modeste, sans éléments graphiques supplémentaires. L’édition de la structure n’est pas si facile : vous devez utiliser le formulaire d’édition pour déplacer la branche. La seule consolation dans cette situation est que la structure de ce guide change rarement.
Pour obtenir les statistiques de ClassExplorer, vous devez ouvrir le formulaire “À propos”, où vous pouvez voir le nombre d’éléments par catégorie.
L’Editeur
Pour créer des pages, Dr.Explain dispose d’un riche ensemble d’outils : contrôle du style de texte, caractéristiques de police, alignement et création de liste.
L’outil d’insertion d’images est tellement cool qu’il mérite une histoire à part, mais pour l’instant je mentionnerai seulement qu’il peut faire des merveilles : dans le processus d’annotation d’une image, il reconnaît l’emplacement des éléments de l’interface utilisateur et leur type, y compris pour les applications écrit en Java.
Les hyperliens internes sont ce qui manque au ClassExplorer (et ne le fera jamais, puisque l’auteur de My Visual Database a suspendu le développement de ce framework). Mais Dr.Explorer les a, et grâce à des algorithmes bien pensés, si le texte et le nom de la section correspondent, la liaison est possible littéralement en un clic.
Dr.Explain peut insérer n’importe quoi dans une page : tableaux, vidéos, code HTML arbitraire.
Il existe un mécanisme de substitution de macro unique : vous pouvez créer des variables de texte dans un document, les insérer dans le texte, puis modifier la valeur de cette variable d’un seul coup. Cette fonctionnalité est utile si vous avez plusieurs projets types avec une description similaire, qui ne diffère que par certains mots-clés pouvant être mis dans des variables. J’ai certainement de tels projets.
Qu’est-ce que ClassExplorer a à offrir contre cela ? Seulement deux choses :
Rechercher des données
Les systèmes d’information créés par Dr.Explain aux formats HTML ou CHM ont un système de recherche intégré : par mots clés et par occurrence de texte. Le premier est rapide, mais pour son travail il demande des efforts supplémentaires de la part de l’auteur : pour chaque page, il faut créer une liste de mots-clés. La deuxième option ne brille pas par la rapidité, mais elle diffère par l’exhaustivité de la couverture.
Conclusion
Il est bien évident que Dr.Explain est avant tout un éditeur avec lequel vous pouvez créer un système d’information : sous la forme d’un ensemble de fichiers HTML ou d’un fichier CHM. Et ClassExplorer est un système d’information avec la possibilité d’éditer des données. Bien que Dr.Explain dispose de fonctionnalités d’édition plus riches, ClassExplorer implémente des algorithmes spécialisés qui sont plus utiles lors de la documentation d’exemples de programmation.
Par l’autorité qui m’est conférée par mon blog, je déclare une trêve : les deux outils restent sur mon étagère en tant que partenaires dans la cause commune du développement de logiciels et de l’éducation.
Liens
Traduction : Yann Yvnec
P.S. Le programme dr.Explain est localisé en français.
