Quando si parla di Developer Experience, pensiamo facilmente a build lente, ambienti locali fragili, pipeline incomprensibili, tool interni, API o golden path.
Molto meno frequentemente trattiamo la documentazione come una vera interfaccia verso la piattaforma e verso l’organizzazione.
Eppure basta osservare cosa accade durante una normale giornata di sviluppo.
Uno sviluppatore cerca come eseguire un servizio localmente. Trova una pagina Confluence. Legge un paragrafo tre volte per capire quale condizione si applichi al suo caso. Scopre due nomi diversi per lo stesso componente. Esegue un comando, ma solo dopo capisce che avrebbe dovuto configurare prima una dipendenza.
La documentazione esiste. È persino corretta. Ma ha comunque prodotto attrito.
Il problema della developer documentation, quindi, non riguarda soltanto quanto documentiamo o quanto velocemente aggiorniamo i documenti. Riguarda anche quanto facilmente un essere umano riesca a trasformare ciò che legge in una decisione o in un’azione.
Ed è proprio qui che uno standard nato decenni fa nell’industria aerospaziale diventa sorprendentemente interessante per un Engineering Leader.
Si chiama ASD-STE100 Simplified Technical English.
Uno standard nato per ridurre l’ambiguità
Simplified Technical English nasce alla fine degli anni Settanta nel settore aeronautico. L’obiettivo originario era rendere la documentazione di manutenzione comprensibile anche a tecnici con una conoscenza limitata dell’inglese. La prima guida fu pubblicata nel 1986; nel 2025 ASD-STE100 è diventato formalmente uno standard internazionale per la documentazione tecnica. L’edizione corrente è Issue 9, datata 15 gennaio 2025.
STE è un controlled natural language: invece di lasciare completamente libera la lingua utilizzata, introduce vincoli per ridurre ambiguità e complessità.
Lo standard contiene due componenti principali: regole di scrittura e un dizionario controllato. La versione corrente contiene 53 writing rules distribuite in nove sezioni. In generale, cerca di associare un significato preciso alle parole, evitare sinonimi inutili, semplificare le strutture grammaticali e rendere esplicite le istruzioni.
Un principio apparentemente banale è particolarmente importante: una cosa dovrebbe avere sempre lo stesso nome.
Se un documento utilizza alternativamente development environment, dev environment, developer environment e local environment per indicare la stessa cosa, il lettore deve continuamente stabilire se siano sinonimi oppure concetti diversi.
ASD-STE100 prova a rimuovere proprio questo tipo di lavoro interpretativo. E per un team software questo è già Developer Experience.
La documentazione ha almeno tre forme di attrito
Quando pensiamo alla qualità della documentazione, conviene separare almeno tre problemi.
| Frizione | Domanda del developer | Esempio |
|---|---|---|
| Findability | Riesco a trovare l’informazione? | La procedura è nascosta in una pagina Confluence non indicizzata |
| Accuracy | Posso fidarmi dell’informazione? | Il README descrive una configurazione non più valida |
| Comprehensibility | Riesco a capire rapidamente cosa devo fare? | La procedura è corretta ma ambigua o inutilmente complessa |
Molte iniziative di documentation improvement lavorano soprattutto sui primi due problemi.
Centralizziamo la knowledge base. Miglioriamo la ricerca. Introduciamo docs-as-code. Associamo ownership ai documenti. Aggiorniamo automaticamente le API reference.
Tutto utile. Ma nessuna di queste cose garantisce che una pagina sia facile da capire quando finalmente la trovi.
ASD-STE100 è interessante proprio perché sposta l’attenzione sulla comprehensibility.
Cosa possiamo prendere da STE senza diventare un’azienda aerospaziale
Non proporrei a un normale Engineering team di diventare ASD-STE100 compliant.
Lo standard è nato per documentazione con caratteristiche e livelli di rischio differenti e prevede regole linguistiche molto più rigorose di quelle necessarie per la maggior parte dei README o dei runbook software.
Lo stesso STEMG, il gruppo che mantiene ASD-STE100, distingue l’uso formale dello standard dall’adozione dei suoi principi in altri contesti. La sua FAQ cita esplicitamente principi come frasi brevi, un solo argomento per frase e active voice come pratiche applicabili anche al di fuori della documentazione per cui STE è stato originariamente progettato.
L’idea più utile è quindi diversa: usare ASD-STE100 come fonte di design principles per la developer documentation, non necessariamente come requisito di conformità.
Da qui possiamo ricavare alcune regole particolarmente efficaci.
1. Una cosa, un nome
STE riduce intenzionalmente i sinonimi e richiede consistenza terminologica. Anche Microsoft raccomanda esplicitamente di utilizzare lo stesso termine per lo stesso concetto.
Per una codebase questo significa, ad esempio, decidere se qualcosa si chiama:
development environment
oppure:
developer environment
e poi mantenere quella scelta tra README, portale interno, CLI, runbook e messaggi di errore.
La consistency non è un vezzo editoriale. Riduce l’incertezza.
2. Una istruzione, una frase
Nelle procedure STE prescrive istruzioni dirette e una sola istruzione per frase. Per le frasi procedurali il limite è 20 parole; per quelle descrittive 25.
Per esempio:
Prima
Update the configuration file and rebuild the service after checking that the new credentials are available in Vault.
Dopo
Make sure that the new credentials are available in Vault.
Update the configuration file.
Rebuild the service.
Non abbiamo aggiunto conoscenza.
Abbiamo ridotto il lavoro necessario per estrarla.
3. Le condizioni vengono prima delle azioni
Se un developer deve conoscere una condizione prima di eseguire un’attività, STE suggerisce di presentarla prima dell’istruzione.
Quindi:
Meno chiaro
Restart the service if you changed the configuration.
Più chiaro
If you changed the configuration, restart the service.
La differenza sembra minima finché una procedura non contiene dieci condizioni e venti passaggi.
4. Preferire l’azione alla narrazione
STE privilegia l’imperativo nelle procedure.
Install the package.
è preferibile a:
The package should be installed.
Nella documentazione software questo principio diventa ancora più importante quando il lettore vuole completare rapidamente un’attività.
Microsoft arriva a una raccomandazione molto simile: per le istruzioni privilegia active voice e formulazioni centrate sull’azione.
5. Ridurre le parole che non modificano l’azione
Termini come simply, basically, normally, usually, properly o easily possono sembrare innocui.
Spesso non aiutano il lettore.
“Properly configure the database” non spiega come riconoscere una configurazione corretta.
“Usually restart the pod” lascia aperta una domanda: quando devo farlo e quando no?
Microsoft suggerisce allo stesso modo di eliminare qualificatori e avverbi che non aggiungono informazione concreta. Microsoft Learn
Before e after: quanto cambia una normale documentazione interna
Consideriamo una procedura plausibile.
Versione iniziale
In case the application has previously been deployed and you’re experiencing issues that might potentially be related to an outdated configuration, it is generally recommended to perform a complete redeployment after ensuring that all the required dependencies have been correctly configured.
Non contiene necessariamente informazioni sbagliate.
Il problema è che il developer deve decomporla mentalmente.
Una possibile riscrittura STE-inspired potrebbe diventare:
If the application uses an old configuration, check its dependencies.
Make sure that all required dependencies are configured.
Deploy the application again.
La nuova versione rende visibili tre cose: condizione → verifica → azione.
È una piccola modifica editoriale.
Ma ripetuta su centinaia di pagine interne può cambiare sensibilmente l’esperienza di utilizzo della documentazione.
La documentazione dovrebbe essere trattata come un’interfaccia
Questo porta a una considerazione più generale.
Un developer portal è un’interfaccia. Una CLI è un’interfaccia. Una API è un’interfaccia. Anche una pagina che spiega come usare quelle cose lo è.
Microsoft osserva esplicitamente che il modo in cui sono scritti help text, messaggi di errore e altre istruzioni influenza l’usabilità del software.
Possiamo quindi pensare alla documentation quality come parte del sistema DevEx.
La domanda non dovrebbe essere soltanto:
“Abbiamo documentato questa funzionalità?”
ma anche:
“Quanto lavoro deve fare lo sviluppatore per trasformare questa documentazione nell’azione corretta?”
Questa seconda domanda cambia il modo in cui valutiamo il problema.
E se la documentazione avesse un linter?
Nel software abbiamo normalizzato un modello molto efficace:
code → lint → review → refactor
Possiamo applicare qualcosa di simile ai documenti:
documentation → language lint → review → rewrite
Alcuni aspetti di STE sono infatti abbastanza strutturati da essere controllati automaticamente: lunghezza delle frasi, passive voice, terminologia, strutture complesse e altri pattern. Anche lo STEMG riconosce che alcuni controlli possono essere automatizzati, pur sottolineando i limiti dei checker.
Con i modelli linguistici diventa possibile andare oltre il semplice conteggio delle parole.
Possiamo chiedere a un LLM di:
- individuare ambiguità;
- verificare consistenza terminologica;
- separare istruzioni multiple;
- spostare prerequisiti e condizioni prima delle azioni;
- identificare parole vaghe;
- proporre una versione più leggibile;
- spiegare perché ogni modifica riduce l’attrito.
Ma questo introduce anche un’importante precauzione.
Il Maintenance Group di ASD ha pubblicato una guida specifica sull’uso dell’AI in ambienti STE: un testo generato da AI può sembrare plausibile e coerente con STE senza esserlo realmente. Lo STEMG insiste quindi sulla necessità di human oversight e di utilizzare ASD-STE100 come riferimento primario quando è richiesta vera conformità.
Per un team software significa distinguere chiaramente due obiettivi.
STE-inspired documentation significa utilizzare alcuni principi dello standard per migliorare la leggibilità.
ASD-STE100 compliant documentation implica invece verificare realmente il documento rispetto allo standard completo e al suo controlled dictionary.
Non sono la stessa cosa.
Un prompt da usare subito con ChatGPT, Claude o Gemini
Per un normale team software partirei dalla modalità STE-inspired, più pragmatica.
Le istruzioni seguenti possono essere inserite nelle Project Instructions di ChatGPT, nelle istruzioni di un progetto Claude o in un sistema equivalente.
Developer Documentation Reviewer — istruzioni pronte all’uso
You are a technical documentation editor for a software engineering organization.
Your goal is to make internal developer documentation clear, precise, consistent, and easy to act on.
Use principles inspired by ASD-STE100 Simplified Technical English, but do not claim ASD-STE100 compliance unless the complete official standard is available to you and the user explicitly requests compliance verification.
When you write or review documentation:
1. Preserve technical accuracy. Never simplify a sentence in a way that changes its technical meaning.
2. Identify whether the text is:
- procedural: tells the developer what to do;
- descriptive: explains a system, behavior, architecture, or concept.
3. For procedural text:
- prefer imperative sentences;
- write one instruction per sentence;
- put prerequisites and conditions before the action;
- prefer active voice;
- keep sentences short;
- as a practical target, keep procedural sentences within approximately 20 words when possible.
4. For descriptive text:
- prefer active voice;
- keep sentences focused on one idea;
- keep paragraphs focused on one topic;
- as a practical target, keep sentences within approximately 25 words when this does not reduce accuracy.
5. Use one term for one concept.
Do not introduce synonyms only to make the writing sound more varied.
If the source uses multiple names for the same concept, identify the inconsistency before changing it.
6. Preserve established software terminology, commands, API names, product names, code identifiers, configuration keys, and domain-specific technical terms.
7. Remove unnecessary words, vague modifiers, and filler such as:
"basically", "simply", "easily", "normally", "properly", "generally",
unless they communicate information that is necessary.
8. Make implicit information explicit when the source provides enough evidence.
Never invent prerequisites, actors, commands, causes, expected results, or system behavior.
9. Prefer:
condition -> action -> expected result
when this sequence matches the actual procedure.
10. Split complex instructions into numbered steps or bullet points when this improves usability.
11. Flag documentation problems that rewriting alone cannot solve, including:
- missing prerequisites;
- contradictory instructions;
- undefined terminology;
- missing ownership;
- outdated information;
- unclear expected results;
- missing recovery or rollback instructions.
12. Do not silently fix uncertain technical claims.
Mark them as requiring verification.
When reviewing an existing document, return:
A. Revised document
B. Main usability problems found
C. Terminology inconsistencies
D. Information that requires technical verification
E. Important changes you made and why
Optimize for the developer completing the task, not for elegant prose.
Clarity, correctness, and consistency are more important than stylistic variety.Questo prompt ha volutamente un obiettivo più limitato della conformità formale STE.
Ed è un vantaggio.
Permette di mantenere termini come deployment, pod, namespace, pull request, feature flag o dead-letter queue quando appartengono realmente al dominio del team, invece di cercare artificiosamente di semplificarli.
Se volete avvicinarvi davvero ad ASD-STE100
È possibile costruire una modalità più rigorosa.
In quel caso conviene richiedere gratuitamente l’Issue 9 ufficiale dal sito dello STEMG e inserirlo tra le fonti del progetto AI. Lo standard ufficiale è disponibile senza costo.
A quel punto aggiungerei alle istruzioni:
STRICT ASD-STE100 MODE
Use the attached official ASD-STE100 standard as the primary source.
When the user explicitly requests Strict ASD-STE100 mode:
- apply the official writing rules;
- verify vocabulary against the official controlled dictionary;
- distinguish approved words from technical nouns and technical verbs;
- report every rule that cannot be verified;
- never invent whether a word is approved;
- preserve technical meaning even when a rewrite becomes more difficult.
Do not state that a document is ASD-STE100 compliant if you cannot verify all applicable rules and vocabulary against the official standard.
When you find a potential violation, report:
- original text;
- applicable ASD-STE100 rule;
- proposed rewrite;
- reason for the change;
- any remaining uncertainty.Questo secondo livello rende l’LLM molto più simile a un reviewer assistito.
Ma continua a non sostituire automaticamente la verifica umana.
Come applicarlo alla documentazione che avete già
Non partirei con un progetto del tipo:
“Riscriviamo tutta la documentazione aziendale.”
È quasi certamente il modo migliore per trasformare un problema DevEx in un programma infinito.
Partirei invece dai documenti nei quali l’attrito costa realmente qualcosa.
Per esempio:
- scegliete 10–20 documenti utilizzati frequentemente per onboarding, local setup, deploy, troubleshooting o incident response;
- raccogliete le domande che gli sviluppatori fanno nonostante quei documenti esistano;
- revisionate i documenti con un set limitato di regole STE-inspired;
- fate validare le modifiche dai subject matter expert;
- osservate se diminuiscono interpretazioni errate, domande ripetitive o tempo necessario a completare il task.
Non serve dimostrare che il nuovo testo sia universalmente “migliore”.
Serve verificare se rende più semplice completare il lavoro per cui il documento esiste.
Cosa misurare
Anche qui eviterei una generica “documentation satisfaction score” come unica metrica.
Più interessanti possono essere segnali vicini al lavoro:
| Segnale | Cosa può indicare |
|---|---|
| Tempo per completare una procedura | Quantità di friction operativa |
| Numero di richieste di chiarimento | Ambiguità o conoscenza mancante |
| Step eseguiti nell’ordine sbagliato | Struttura procedurale insufficiente |
| Incident o errori collegati alla procedura | Conseguenze della documentazione |
| Search → document → task completion | Utilità effettiva del contenuto |
| Feedback “questa pagina non mi ha aiutato” | Punto di partenza qualitativo |
Non tutte queste metriche saranno disponibili.
E la causalità è difficile: un miglioramento può dipendere anche dal tooling o dalla piattaforma.
Per questo un piccolo esperimento su una critical developer journey può essere più informativo di un programma aziendale di riscrittura.
Non tutto deve essere semplificato
C’è infine un rischio opposto. Technical writing semplice non significa technical writing superficiale.
Un CTO non dovrebbe chiedere ai team di sostituire termini precisi con parole generiche soltanto perché sono più comuni.
Una idempotency key resta una idempotency key. Una race condition non diventa necessariamente “a problem that happens when two things occur together”.
La documentazione tecnica richiede un vocabolario tecnico.
STE stesso prevede l’esistenza di technical nouns e technical verbs specifici dell’azienda, del settore o della materia trattata.
Il principio corretto non è quindi: usare sempre parole semplici.
È: non rendere complesso ciò che può essere espresso con precisione in modo semplice.
Da “abbiamo scritto la documentazione” a “il developer riesce a usarla”
La maggior parte delle organizzazioni software non ha bisogno di diventare ASD-STE100 compliant.
Ma la filosofia che sta dietro allo standard pone una domanda molto utile alla Developer Experience: quanto lavoro interpretativo stiamo scaricando sul lettore?
È una domanda che possiamo applicare a un README come a un runbook, a un developer portal come a una pagina di onboarding.
Documentare qualcosa non significa soltanto trasferire informazione.
Significa progettare il percorso che porta qualcuno dall’informazione all’azione.
Ed è per questo che la qualità della scrittura non è soltanto un problema editoriale.
È parte dell’interfaccia che il nostro Engineering system offre ai suoi sviluppatori.
