La plupart des sites web de documentation d’entreprise qui comportent des blocs de code utilisent des styles indiquant qu’il s’agit de balises de position. L’intention est censée être claire, et les lecteurs sont censés savoir ce qu’ils doivent modifier, mais l’expérience n’est pas à la hauteur.
Ces mêmes styles sont également utilisés pour mettre en évidence des éléments, des libellés d’interface utilisateur ou la syntaxe à d’autres endroits de la documentation. Parmi les marqueurs de position couramment utilisés par les équipes de rédaction technique pour identifier les blocs de code, et qui sont également employés pour d’autres styles, on trouve :
- Italique
- {Accolades}
- Gras
- exemple_nom_##
- TOUT EN MAJUSCULES
- Une combinaison des éléments ci-dessus
- Quelque chose de complètement différent
Ce chevauchement rend le suivi et la gestion des espaces réservés plus complexes qu’ils ne devraient l’être. À petite échelle, cela peut sembler n’être qu’un simple désagrément. Mais à mesure que les bibliothèques de documentation s’étoffent et se diffusent entre les équipes et au fil des années, cela crée des problèmes tant pour les auteurs que pour les lecteurs. Ce qui est censé simplifier la gestion des espaces réservés la complique au contraire, car le même style est réutilisé ailleurs.
Le résultat peut vous placer dans une situation familière : vous devez comprendre la convention relative aux espaces réservés et tenter de tous les mettre à jour si vous voulez réussir. Si vous en oubliez un, la commande risque de ne pas fonctionner comme prévu. D’autres problèmes peuvent survenir, tels que des erreurs, des configurations inattendues, voire des paramètres dont vous ne saviez pas qu’ils pouvaient être modifiés. Les autres approches des blocs de code ont leurs limites :
- Les blocs statiques (avec ou sans mise en évidence de la syntaxe) sont indispensables lorsque vous connaissez déjà les valeurs. Ils sont rapides et prêts à être copiés pour être exécutés. Ils constituent la meilleure solution lorsque vous n’avez rien à modifier.
- Les éditeurs en ligne vont à l’autre extrême et vous permettent de mettre à jour le texte directement dans le bloc de code, mais souvent au détriment du contexte : la fonction « annuler » devient peu fiable et de petites erreurs effacent la structure dont vous avez besoin.
- Les éditeurs d’API pour développeurs vous permettent de tester des requêtes en temps réel, et ils sont particulièrement adaptés lorsque le public principal est constitué de développeurs travaillant directement avec des API. Mais la documentation d’entreprise remplit des rôles et des cas d’utilisation plus larges, et ce type d’interactivité fait souvent défaut là où il pourrait apporter une valeur ajoutée.
Combler le fossé grâce aux blocs de code interactifs
Nos blocs de code interactifs comblent cette lacune en transformant une partie historiquement fragile de la documentation (l’espace réservé) en un élément clair, modifiable et évolutif.
Vous disposez de la même commande qu’auparavant, avec la même mise en page et la même structure, mais désormais, les espaces réservés sont devenus des champs modifiables. Chacun d’entre eux porte une étiquette claire (comme auparavant), ce qui vous évite d’avoir à interpréter des symboles ou à vous fier à des suppositions.
Vous mettez à jour les valeurs directement dans le bloc, tout en conservant le contexte environnant à l’écran. Cela signifie que vous voyez l’exemple, le reste du contenu de la page et vos saisies au même endroit. Cela peut vous aider à créer un extrait de code plus pertinent avant de cliquer sur « Copier ».
Vous pouvez modifier ces valeurs avant de les copier ou les laisser telles quelles et les modifier plus tard dans un autre éditeur. Les espaces réservés d’un bloc de code portant le même nom sont liés. Lorsque vous modifiez la valeur d’un champ d’espace réservé au-dessus du bloc de code, tous les champs liés peuvent être mis à jour simultanément, ce qui vous permet de modifier de manière plus cohérente les champs qui partagent la même valeur d’espace réservé. Cela permet de réduire les erreurs potentielles de recherche et de remplacement lorsque vous travaillez dans un éditeur de texte.
L’évolution de l’expérience utilisateur
Cette évolution résout deux problèmes à la fois. Pour les lecteurs, elle réduit les conjectures et prévient les erreurs. Plus besoin de déchiffrer les accolades ou les crochets angulaires. Pour les rédacteurs, elle sépare la sémantique de la mise en forme, permettant ainsi de suivre, de contrôler et de mettre à jour les espaces réservés par programmation. Cela ouvre la voie à la gestion des versions, aux règles de validation et à la cohérence entre les environnements. Les incohérences héritées du passé sont corrigées au fur et à mesure, ce qui facilite la maintenance globale de la bibliothèque.
Les blocs de code interactifs transforment l’un des aspects les plus complexes de la documentation, à savoir les espaces réservés basés sur le style, en un élément précis, facile à maintenir et rapide à utiliser. L’expérience donne l’impression d’être mûrement réfléchie plutôt qu’improvisée. Et pour la première fois, la gestion des exemples de code à grande échelle devient une source d’opportunités d’amélioration plutôt qu’un obstacle.
Disponible dès maintenant pour les logiciels, le SaaS et bien plus encore
Cette expérience est déjà disponible sur notre site de documentation dédié aux logiciels (versions 11.42, 11.40, 11.36 et 11.32), au SaaS et à d’autres sites connexes sur https://documentation.commvault.com/.
Essayez-la la prochaine fois que vous naviguez et tombez sur un bloc de code : modifiez quelques champs, cliquez sur « Copier » et constatez à quel point il est plus facile de se lancer après l’avoir importé dans votre éditeur.
Remarques :
- Vérifiez attentivement tout code avant de l’exécuter, qu’il provienne d’un bloc de code interactif ou statique.
- Lorsque vous actualisez une page après avoir modifié des espaces réservés dans un bloc de code interactif, tous les espaces réservés modifiés reprennent leurs valeurs par défaut.
Pour en savoir plus sur l’utilisation des blocs de code, cliquez ici.
