La plupart des sites web de documentation d’entreprise qui comportent des blocs de code utilisent des styles indiquant qu’il s’agit de marques 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 marques de position couramment utilisées par les équipes de rédaction technique pour identifier les blocs de code,et qui sont également employées pour d’autres styles,on trouve :
- Italics
- {Accolades}
- Bold
- exemple_nom_##
- TOUT EN MAJUSCULES
- Une combinaison des éléments ci-dessus
- Quelque chose de complètement différent
This overlap makes placeholder tracking and management more complex than it should be. On a small scale,this can feel like a nuisance. But as documentation libraries grow and spread across teams and years,it creates problems for both authors and readers. What is meant to simplify placeholder management instead complicates it,because the same styling is reused elsewici.
The result can put you in a familiar position: You must figure out the placeholder convention and attempt to update them all if you want to succeed. If you miss one placeholder,the command may not work as expected. Other issues can appear,such as errors,unexpected configurations,or even settings you didn’t know could be changed.
Other code block approaches only go so far:
- Static blocks (with or without syntax highlighting) are essential when you already know the values. They are fast and copy-to-run ready. These are best when you don’t need to modify anything.
- Inline editors go to the other extreme and enable you to update text directly within the code block,but often at the expense of context – undo becomes unreliable and small mistakes erase the structure you need.
- Developer API editors let you try out requests in real time,and they’re a great fit when the main audience is developers working directly with APIs. But enterprise documentation serves broader roles and use cases,and that style of interactivity is often missing wici it would still add value.
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.
You get the same command as before with the same formatting and structure,only now the placeholders have become editable fields. Each one has a clear label (like before) so you don’t have to interpret symbols or rely on guesswork.
You update the values right inside the block,with the surrounding context still visible. That means you see the example,the rest of the page’s contents,and your inputs all in one place. It can help you shape a more relevant snippet before you click Copy.
You can change those values before copying them or leave them as-is and edit them later in another editor. Either way,the structure stays the same and what you copy reflects exactly what you see in the block.
Placeholders in a code block that have the same name become linked. When you change the value of a placeholder field above the code block,all linked fields can update at the same time so that you can more consistently edit fields that have the same placeholder value. This helps reduce potential find and replace mistakes when working in a text editor.
Le changement d’expérience
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,d’auditer 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 dans les domaines des logiciels,SaaS et plus encore
This experience is already live across our documentation site for Software (versions11.42,11.40,11.36,and 11.32),SaaS,and other related sites on https://documentation.commvault.com/.
Try it out the next time you browse and run across a code block – edit a few fields,click “Copy,” and see how much easier it is to get started after you bring it into your editor.
Remarques :
- Carefully review any code before you run it,whether it’s from an interactive or static code block.
- When you refresh a page after changing placeholders in an interactive code block,all changed placeholders revert to their default values.
Pour en savoir plus sur l’utilisation des blocs de code, cliquezici.
