Linee guida della documentazione

Questa pagina definisce le regole operative del manuale utente. Se il manuale viene aggiornato senza rispettarle, il testo, gli screenshot e le copie localizzate iniziano a divergere e il risultato diventa meno utile per chi lo apre per la prima volta.

Regole sugli screenshot

Regola	Requisito
Inquadratura	Preferisci catture 16:9 a 1920×1080 per ogni screenshot, anche per i passaggi compatti.
Tema	Ogni pagina deve mostrare una sola variante dello screenshot alla volta. Non mettere insieme versioni light e dark nella stessa sezione.
Lingua	Ogni screenshot deve avere varianti per en, it, de ed es.
Asset	Salva le sorgenti generate in src/assets/screenshots/<locale>/.... Mantieni gli URL /screenshots/... nei docs e sincronizza in public/screenshots prima della build.
Immagini	Usa il set curato in src/assets/images per il seed degli screenshot. Mantieni asset portrait, landscape, sport, product e mixed editorial e documenta l'autore di ogni file.
Nomenclatura	Usa un nome studio realistico come Aurora Frame Studio. Non mostrare mai E2E, ID di test o etichette finte nell'interfaccia visibile. Usa favicon.svg come logo dello studio fittizio, cosi e visibile nell'app.
Passaggi mini	Usa uno screenshot compatto solo per un passaggio breve, uno stato di errore o una conferma che sta in una sola schermata.

Attribuzione Unsplash

Il seed degli screenshot usa un piccolo set di immagini locali in src/assets/images:

File	Autore	Pagina Unsplash
portrait-man.jpg	Kunal Tangal	https://unsplash.com/photos/mans-portrait-MeD_q1TMZYE
portrait-woman.jpg	Leonid Shaydulin	https://unsplash.com/photos/a-woman-with-long-hair-ZwjUU6f9DQE
wedding-pose.jpg	Myron Edwards	https://unsplash.com/photos/a-bride-and-groom-pose-for-a-picture-vIEhfrHAcRY
landscape-couple.jpg	Micah & Sammie Chaffin	https://unsplash.com/photos/a-couple-embraces-in-a-vast-open-landscape-RZXESXzhnuU
landscape-walk.jpg	Tom Pumford	https://unsplash.com/photos/wedding-couple-holding-hands-while-walking-XiiexZ2jjrI

Regole di scrittura

• Descrivi cosa deve fare il lettore, non solo ciò che vede.
• Le didascalie devono essere fattuali. Devono spiegare il risultato del passaggio, non presentare dark mode o una vista ridotta come se fossero una vetrina.
• Usa ThemeScreenshot quando un flusso richiede uno screenshot che cambia con il tema, ma mostra sempre una sola variante per sezione.
• Usa ImageZoom per gli screenshot che meritano un ingrandimento.
• Usa starlight-kbd per scorciatoie e tasti, invece di scrivere i nomi a mano.
• Nascondi i devtools di TanStack e gli altri controlli floating di debug negli screenshot del manuale.

Checklist qualità

Prima di pubblicare una pagina nuova o modificata, verifica che:

1. La pagina esista in tutte le lingue disponibili.
2. Ogni path immagine risolva nella lingua corretta.
3. Gli screenshot che dipendono dal tema non mostrino mai light e dark nella stessa sezione.
4. Le immagini Unsplash siano presenti dove l'app altrimenti mostrerebbe pannelli vuoti o grigi, e l'attribuzione sia documentata.
5. Il testo non contenga E2E in nessun punto visibile al lettore.
6. Il logo dello studio fittizio risolva a favicon.svg e sia visibile nella chrome dell'app.
7. Gli screenshot mini siano davvero compatti e spieghino un solo passaggio.

Quando aggiornare questa pagina

Aggiorna le linee guida quando cambia la pipeline degli screenshot, la logica di localizzazione o lo stile del manuale. L'obiettivo resta mantenere il manuale 1:1 con l'app e con gli asset che la rappresentano.