In un documento tecnico spesso vengono utilizzati termini ed acronimi molto specialistici.
Ma colui che dovrà leggere il documento, sarà in grado di interpretare correttamente tali contenuti?
La risposta più facile e "pigra" è SI, ed è la risposta che ci "scarica" dalla responsabilità di un ulteriore sforzo per migliorare la comprensione del documento.
In realtà, è SEMPRE buona norma corredare i nostri documenti di un Glossario, cioè di una raccolta specifica e circoscritta dei termini specialistici presenti nel documento, accompagnati dalle relative spiegazioni.
Quali sono i principali criteri da utilizzare per costruire un Glossario?
- Focalizzare l'audience del documento
- Scegliere i termini da inserire
- Progettare un design essenziale
- Gestirne l'evoluzione nel tempo
Avendo chiari in mente questi 4 punti cardinali, siamo già a buon punto.
FOCALIZZARE L'AUDIENCE DEL DOCUMENTO
Come sempre, scriviamo per qualcuno. Una delle regole auree della scrittura tecnica ci impone di immaginare chi leggerà il nostro documento.
E' un principiante? Allora dovremo inserire nel Glossario anche le voci che non metteremmo se invece ci rivolgiamo ad un utente esperto. Se il mio manuale parla del funzionamento di un software e lo legge un Ingegnere Informatico, forse non devo spiegare cosa sia una GUI (Graphic User Interface).
Altrimenti, è preferibile inserire tale acronimo nel Glossario.
Idem per altri acronimi, quali CPU o RAM o SOAP.
Tuttavia, mi è capitato di recente che un tecnico mi chiedesse lumi sull'acronimo SAML (Security Assertion Markup Language). In effetti, anche un esperto di informatica, se non è specializzato nel campo della sicurezza e della crittografia, potrebbe non aver mai avuto a che fare con lo standard SAML.
In linea di massima, io adotto la regola di inserire nel Glossario TUTTI gli acronimi presenti nel documento (ad eccezione dei più universalmente noti), sforzandomi tuttavia di ridurre al minimo indispensabile la loro presenza nel corpo del documento.
Identificare chiaramente il lettore target, è il primo filtro per individuare il set di termini "candidati" ad entrare nel Glossario.
A presto per approfondire la tematica.
Nessun commento:
Posta un commento