La maggior parte dei siti web di documentazione aziendale che contengono blocchi di codice utilizza stili che indicano i segnaposto. L’intento dovrebbe essere chiaro e i lettori dovrebbero sapere cosa devono modificare, ma l’esperienza non è all’altezza delle aspettative.
Questi stessi stili vengono utilizzati anche per l’enfasi, le etichette dell’interfaccia utente o la sintassi in altre parti della documentazione. Tra gli stili comunemente utilizzati dai team di redazione tecnica per identificare i blocchi di codice, che vengono impiegati anche per altri scopi, figurano:
- Corsivo
- {Parentesi}
- Grassetto
- nome_esempio_##
- TUTTO MAIUSCOLO
- Una combinazione delle precedenti
- Qualcosa di completamente diverso
Questa sovrapposizione rende il monitoraggio e la gestione dei segnaposto più complessi di quanto dovrebbero essere. Su piccola scala, ciò può sembrare un fastidio. Ma man mano che le librerie di documentazione crescono e si diffondono tra i team e nel corso degli anni, crea problemi sia per gli autori che per i lettori. Ciò che dovrebbe semplificare la gestione dei segnaposto, invece, la complica, poiché lo stesso stile viene riutilizzato altrove.
Il risultato può metterti in una situazione familiare: devi capire la convenzione dei segnaposto e cercare di aggiornarli tutti se vuoi ottenere risultati positivi. Se tralasci un segnaposto, il comando potrebbe non funzionare come previsto. Possono presentarsi altri problemi, come errori, configurazioni inaspettate o persino impostazioni che non sapevi potessero essere modificate. Altri approcci basati su blocchi di codice hanno un raggio d’azione limitato:
- I blocchi statici (con o senza evidenziazione della sintassi) sono essenziali quando i valori sono già noti. Sono veloci e pronti per essere copiati ed eseguiti. Sono l’ideale quando non è necessario modificare nulla.
- Gli editor in linea rappresentano l’estremo opposto e consentono di aggiornare il testo direttamente all’interno del blocco di codice, ma spesso a scapito del contesto: l’annullamento diventa inaffidabile e piccoli errori cancellano la struttura necessaria.
- Gli editor API per sviluppatori consentono di testare le richieste in tempo reale e sono ideali quando il pubblico principale è costituito da sviluppatori che lavorano direttamente con le API. Tuttavia, la documentazione aziendale ha ruoli e casi d’uso più ampi e spesso questo tipo di interattività manca proprio dove potrebbe aggiungere valore.
Colmare il divario con blocchi di codice interattivi
I nostri blocchi di codice interattivi colmano questa lacuna trasformando una parte storicamente fragile della documentazione (il segnaposto) in qualcosa di chiaro, modificabile e scalabile.
Si ottiene lo stesso comando di prima con la stessa formattazione e struttura, solo che ora i segnaposto sono diventati campi modificabili. Ciascuno ha un’etichetta chiara (come prima), quindi non è necessario interpretare simboli o affidarsi a supposizioni.
Puoi aggiornare i valori direttamente all’interno del blocco, con il contesto circostante ancora visibile. Ciò significa che puoi vedere l’esempio, il resto dei contenuti della pagina e i tuoi inserimenti tutti in un unico posto. Questo può aiutarti a creare uno snippet più pertinente prima di cliccare su “Copia”.
Puoi modificare quei valori prima di copiarli oppure lasciarli così come sono e modificarli in un secondo momento in un altro editor. In entrambi i casi, la struttura rimane la stessa e ciò che copi riflette esattamente ciò che vedi nel blocco. I segnaposto in un blocco di codice che hanno lo stesso nome vengono collegati. Quando modifichi il valore di un campo segnaposto sopra il blocco di codice, tutti i campi collegati possono essere aggiornati contemporaneamente, in modo da poter modificare in modo più coerente i campi che hanno lo stesso valore segnaposto. Ciò contribuisce a ridurre i potenziali errori di ricerca e sostituzione quando si lavora in un editor di testo.
Il cambiamento nell’esperienza
Questo cambiamento risolve due problemi contemporaneamente. Per i lettori, riduce le congetture e previene gli errori. Non è più necessario decifrare le parentesi graffe o quelle angolari. Per gli autori, separa la semantica dallo stile, consentendo di tracciare, verificare e aggiornare i segnaposto a livello di programmazione. Ciò sblocca la gestione delle versioni, le regole di convalida e la coerenza tra i vari ambienti. Le incongruenze preesistenti vengono corrette man mano, rendendo la libreria complessiva più facile da mantenere.
I blocchi di codice interattivi trasformano una delle parti più complesse della documentazione, i segnaposto basati sullo stile, in qualcosa di preciso, gestibile e veloce da usare. L’esperienza appare intenzionale anziché improvvisata. E per la prima volta, la gestione su larga scala degli esempi di codice crea opportunità di miglioramento anziché ostacoli.
Ora disponibile in Software, SaaS e altro ancora
Questa esperienza è già disponibile sul nostro sito di documentazione per il software (versioni 11.42, 11.40, 11.36 e 11.32), SaaS e altri siti correlati su https://documentation.commvault.com/.
Provatela la prossima volta che navigate e vi imbattete in un blocco di codice: modificate alcuni campi, fate clic su “Copia” e scoprite quanto sia più facile iniziare dopo averlo importato nel vostro editor.
Note:
- Esaminate attentamente qualsiasi codice prima di eseguirlo, sia che provenga da un blocco di codice interattivo o statico.
- Quando si aggiorna una pagina dopo aver modificato i segnaposto in un blocco di codice interattivo, tutti i segnaposto modificati tornano ai valori predefiniti.
Per saperne di più sull’uso dei blocchi di codice, clicca qui.
