“Scrivi una volta, pubblica ovunque”

Mi rivolgo a tutti coloro che si occupano di produzione di contenuti: la gestione dei dati e delle informazioni, e il loro corretto riutilizzo nella documentazione tecnica complessa, stanno diventando sempre più importanti per rendere il lavoro più efficiente.
Ma saperlo fare con efficacia è più difficile.

Hai mai sentito parlare di il Single Sourcing?

Nella documentazione tecnica si declina in questo principio: devi scrivere i tuoi contenuti una sola volta, in un unico posto (una “singola fonte”) e poi essere in grado di:

  • Utilizzare il contenuto che hai creato in più contesti, ad esempio per produrre documentazione per diversi prodotti o altre varianti, invece di dover copiare e incollare.
  • Pubblicare i tuoi contenuti in diversi formati e media: PDF, HTML, Mobile, ecc.

Ovviamente l’obiettivo finale è una produzione e una gestione dei contenuti più efficienti. “Make It Easy to Reuse”

L’insegnamento dei principi e tecniche di programmazione 

I programmatori si sono trovati a risolvere le stesse problematiche di chi deve occuparsi di redazione di contenuti riutilizzabili e hanno codificato dei principi che possono esserci utili da tenere a mente per creare contenuti riutilizzabili.

1. Keep It Simple, Stupid (KISS)

Significa che dovresti scrivere nel modo più semplice possibile. Non lasciarti prendere dal tentativo di essere eccessivamente intelligente o esibirti con un paragrafo arzigogolato. Se riesci a esprimere un concetto in una sola riga, scrivilo in una riga. Nella programmazione, questo si riferisce al fatto che ci sono sempre molti modi per ottenere funzionalità, ma il modo più semplice è solitamente il migliore. (I colti si possono rifare al rasoio di Occam come a un principio simile.)

2. Don’t Repeat Yourself  (DRY)

Il principio Don’t Repeat Yourself (DRY) significa chiaramente non ripeterti. È un errore abbastanza comune. L’idea stessa del single-sourcing è che dovresti iniziare a pensare che ogni volta che ti “ripeti” potresti, oltre che perdere tempo, fare qualcosa di sbagliato.

Quindi, invece di ripetere lo stesso contenuto in più posti, devi pensare: esiste un modo in cui posso riutilizzare questo contenuto?

3. Principio della conoscenza minima”Principle of Least Knowledge” o legge di Demetra (Law of Demeter, spesso abbreviata in “LoD”)

Questo principio può essere tradotto col motto “non parlate con gli sconosciuti”.

Dovresti mirare a rendere i tuoi argomenti “autonomi” e, ad esempio, fare attenzione a non creare “dipendenze” tra i tuoi blocchi di contenuto. Per essere più concreti: non creare collegamenti tra frasi inutilmente. E se vuoi mirare a rendere gli argomenti riutilizzabili in molti contesti diversi (ad esempio documentazione per più prodotti), allora non puoi dare per scontato che un argomento “altro” a cui ti colleghi, in un contesto di pubblicazione diverso, sarà effettivamente presente.

4.  Principio di singola responsabilità (single responsibility principle, abbreviato con SRP)

Questo principio si riferisce all’idea che un argomento dovrebbe avere solo una responsabilità, o compito. Ciò significa  che dovrebbe soddisfare solo uno scopo.

Se mescoli due tipi di informazione in uno stessa frase, diventa poi difficile poterla riutilizzare. Allora rifattorizza e suddividile in frasi e blocchi più piccoli.

5 Non ne avrai bisogno ( you ain’t gonna need it YAGNI)

Secondo questo principio un programmatore non dovrebbe sviluppare software che implementi funzionalità non esplicitamente richieste. Vale a dire: non cercare di risolvere un problema che non esiste. Nel tentativo di scrivere “DRY”, alcuni possono tradire questo principio se cercano di scrivere il più astratto e generico possibile. Applicare il principio DRY solo quando è necessario.

6. Principio di astrazione e generalizzazione  (principle of abstraction)

Laddove funzioni simili sono svolte da pezzi di codice distinti, è generalmente vantaggioso combinarli in uno solo lasciando da parte le parti variabili. 

In altre parole: se hai la possibilità di rendere una funzione generica invece che specifica, fallo,  se la rendi troppo specifica, non sarà riutilizzabile.

Nel contesto della scrittura tecnica, vale la stessa cosa:  se hai la possibilità di rendere un argomento più “generico” conservando la comprensione, fallo. Ad esempio, immagina di scrivere di due prodotti diversi, ma simili. Hanno la stessa descrizione, stesse informazioni sulla sicurezza e così via e l’unica cosa che differisce è il nome del modello. Ciò che questo principio dice è: se non hai davvero bisogno di menzionare il nome del modello del prodotto, non farlo! 

Per concludere

Lascia il tuo ego fuori dalla porta ed evita di scrivere in modo cervellotico.
Non stai scrivendo per impressionare gli estranei.
Non cercare di racchiudere una tonnellata di concetti in una riga.
Se ciò che scrivi è facile da leggere, sarà facile da mantenere e facile da tradurre.
Ricorda che, in un mondo globalizzato, i tuoi testi dovranno essere tradotti. Molto probabilmente 80% di chi leggerà ciò che hai scritto lo leggerà con le parole del traduttore e come lui l’ha compreso.
Cerca di essere chiaro.

EKR Orchestra® ti può essere d’aiuto.

Scopri EKR Orchestra qui

Giorgio Saleri
Business Developer

Leave a reply:

Your email address will not be published.

captcha
- Dichiaro di aver letto l'informativa sulla privacy ed acconsento al trattamento dei dati

Site Footer

Sliding Sidebar

Iscriviti alla newsletter

Iscriviti alla newsletter

Resta informato ricevi tutte le ultime notizie!

You have Successfully Subscribed!