# General Translation Blog: Progettare documentazione per le persone
URL: https://generaltranslation.com/it/blog/designing-docs-for-humans.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Perché il design conta ancora nell'era dell'IA e i principi con cui progettiamo la nostra documentazione per fare ordine nel disordine mentale.
Authors: Kevin Liu, Taylor Fang
Published: 2026-09-17
## Perché progettare la documentazione?
La documentazione è un problema aperto nel design web. Ci sono pattern e anti-pattern ovunque, replicati all'infinito nei template preconfezionati. I template sono veloci e comodi, ma rischiano di trattare la documentazione come un aspetto secondario, invece che come una parte centrale dell'esperienza di prodotto da progettare per l'utente specifico. Inoltre, le soluzioni più diffuse sono spesso sovraprogettate e sovraccariche di effetti visivi. Crediamo che i siti di documentazione abbiano bisogno di **un'esperienza di lettura più semplice e incentrata sul contenuto**, lasciando i design più elaborati al sito di marketing (ispirandoci alla filosofia del [creatore di Fumadocs](https://generaltranslation.com/blog/fuma-nama)).
Ma in un mondo in cui gli agenti sono la maggioranza dei lettori di documentazione, oltre che dei suoi autori, **ha ancora senso progettare il proprio sito di documentazione?** Perché mai investire nella leggibilità per le persone e nel design visivo?
Crediamo che un'interfaccia di documentazione intuitiva e intenzionale diventi ancora più importante nel mondo dell'AI slop. La nostra convinzione nasce dalla cura per il mestiere del design e dall'ossessione per l'esperienza del nostro prodotto. Ma nasce anche da una constatazione: **le persone continuano a guardare e leggere la documentazione**. Sì, gli agenti sono esecutori di codice su larga scala, ma le statistiche sui volumi non raccontano tutto. Le persone continuano a consultare i siti di documentazione per capire e valutare un prodotto. E hanno sempre più bisogno di interfacce che ripuliscano il disordine mentale e indirizzino l'attenzione verso ciò che conta.
Abbiamo affrontato la riprogettazione della nostra documentazione da zero, partendo dai percorsi utente paralleli che avevamo esplorato nella [riscrittura dei contenuti](https://generaltranslation.com/blog/rewriting-our-docs). Le primitive della documentazione sono poche: navigazione, ricerca, controlli, link e contenuto. Le abbiamo disposte con meno linee e più spazio aperto, per un'esperienza visiva più pulita, basandoci sul framework di documentazione open-source [Fumadocs](https://generaltranslation.com/blog/fuma-nama) per ottenere la massima componibilità.
Lavoriamo con impegno sui nostri testi e vogliamo che le persone li leggano. L'obiettivo costante è progettare e mantenere un sito di documentazione che renda la lettura scorrevole e persino piacevole. Lungo il percorso abbiamo sviluppato alcuni principi di design fondamentali. Il primo è adottare un'interfaccia familiare e comprensibile.
## Flusso intuitivo e direzione
La documentazione aiuta gli utenti a costruire un modello mentale del prodotto e del suo funzionamento, come [abbiamo raccontato](https://generaltranslation.com/en-US/blog/rewriting-our-docs) nell'articolo del nostro blog dedicato alla ristrutturazione dei contenuti della documentazione. Il nostro design nasce dagli stessi principi di fondo: un'organizzazione intenzionale e significativa, complessità e personalizzazione rivelate in modo progressivo, dettagli discreti e persino invisibili.
Ogni area dello schermo **corrisponde a un'azione o a un output unificato**, così le funzioni compaiono dove gli utenti si aspettano di trovarle. (Poiché abbiamo notato che alcuni utenti hanno una forte preferenza per i temi visivi, il selettore della modalità compare in due aree.)
La pagina, inoltre, supporta un flusso intuitivo, **guidando gli utenti verso ciò che vogliono ottenere**.
La documentazione mette in evidenza i link alle azioni che gli utenti potrebbero voler compiere: consultare il Registro delle modifiche per gli aggiornamenti, porre una domanda al supporto oppure richiedere una demo del prodotto.
## Eliminare il disordine mentale
Le interfacce sono sempre più affollate. Elementi come il “testo occhiello”, animazioni casuali che si muovono in più dimensioni e riquadri superflui (con angoli arrotondati) sono i segni inequivocabili del design generato dall'IA. **La conseguenza di questo disordine visivo è un corrispondente disordine mentale.** Quando ogni componente esiste fine a sé stesso, senza una collocazione ponderata e una relazione con gli altri componenti, il significato si dissolve.
Il nostro primo compito è quindi **eliminare il disordine mentale**. Ciò significa rimuovere gli elementi superflui; nel nostro caso, molte righe, link e pulsanti in eccesso.
Ma significa anche strutturare, riorganizzare e semplificare radicalmente. In particolare, abbiamo consolidato le superfici di navigazione, intese come la mappa che **organizza e indica i concetti mentali del sito**.
La nostra barra laterale è ora un unico accordion. Non sembra una rivoluzione, ma è ormai una rarità nei siti di documentazione, che spesso mostrano più barre di navigazione delle sezioni in più punti, sia in verticale che in orizzontale.
La CI impone una gerarchia chiara per la barra laterale, impedendole di diventare un elenco scoraggiante di link e opzioni tutti allo stesso livello. Ed è persistente: cliccare su un link non stravolge le opzioni della barra laterale né ti fa perdere il segno quando provi a tornare indietro.
## Guidare lo sguardo
Un flusso intuitivo insegna anche all'utente come muoversi nell'interfaccia. Volevamo attirare naturalmente lo sguardo dell'utente verso le aree importanti **introducendo una maggiore gerarchia visiva**: per la navigazione, i controlli, i contenuti e le azioni.
a) Usare le icone nelle aree importanti per spezzare i muri di testo.
b) Aggiungere più separatori tra le sezioni di testo per raggruppare i contenuti e rendere più evidenti le divisioni tra una sezione e l'altra.
c) Differenziare lo stile del testo, ricorrendo anche al corsivo (che nella documentazione si tende a temere) e abbassando il peso a 400 per il testo del corpo.
Volevamo soprattutto creare molto spazio bianco per dare respiro ai contenuti, ispirandoci alla [documentazione di Linear](https://linear.app/docs). La riprogettazione della pagina Quickstart aiuta a illustrare questi principi applicati nell'insieme.
## Un tocco distintivo di GT
I siti di documentazione restano pagine web e non devono risultare spenti. Pur facendo attenzione a non esagerare con il design e a non distogliere l'attenzione dal contenuto, abbiamo aggiunto dettagli di "micro-UI" per integrare la nostra documentazione nell'estetica e nel mondo del marchio GT.
Abbiamo costruito un'interazione discreta sull'[iconico componente table-of-contents di Fumadocs](https://generaltranslation.com/en-US/blog/fuma-nama/#the-fumadocs-design-credo). Funziona con il rendering server-side come maschera SVG, con un livello di annidamento di 12px e un cursore azzurro tenue che segue il puntatore. Il pannello mobile disegna la stessa geometria in modo statico, dato che sul touch non esiste l'hover.
Abbiamo applicato la stessa maschera alla barra laterale. Scorrendo una sezione dall'alto verso il basso, il cursore azzurro scivola lungo la guida, piegandosi verso l'interno dove il tree si annida e seguendo il puntatore riga dopo riga.
Abbiamo inoltre selezionato con cura altre primitive di UI per contrastare i sintomi tipici del design generato dall'IA. Usiamo icone piene ovunque un'icona abbia un significato, e manteniamo glifi sottili a contorno per controlli come la ricerca e la copia. I riquadri hanno angoli meno arrotondati. Abbiamo implementato barre di scorrimento coerenti tra barra laterale, code blocks e menu, al posto del consueto miscuglio di barre native e overlay. E per il language switcher usiamo SVG di bandiere personalizzati anziché emoji flag, così da preservare un'iconografia visiva opaca e richiamare la nostra landing page.
E naturalmente, la nostra esperienza di localization della documentazione deve essere di primo livello: spaziature, allineamenti e ordine devono restare intatti.
## La lista nera
Durante tutto il processo abbiamo stilato una "lista nera" degli anti-pattern che ci sono saltati all'occhio.
* Testo occhiello
* Testo esplicativo superfluo messo a caso
* Riquadri con angoli troppo arrotondati
* Icone non piene
* Spaziatura variabile slegata dall'importanza del contenuto
* Documentazione non localizzata (!)
* Troppi elementi di navigazione sparsi per la pagina
* Barre laterali che sembrano espandersi all'infinito
* Barre laterali che cambiano quando clicchi su qualcosa
* Barre laterali in cui si perde il segno
Naturalmente continuiamo a lavorare per migliorare il design della nostra documentazione e ogni feedback è benvenuto. Buona progettazione!
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.