Linee Guida Della Documentazione Drone Sky Check

Le linee guida definiscono le regole per costruire e mantenere la documentazione ufficiale di Drone Sky Check.

Questo documento è una guida editoriale e tecnica interna alla documentazione. Non è la Home pubblica del prodotto e non deve sostituire le pagine utente o sviluppatore.

Infrastruttura

La documentazione sorgente vive in:

docs/

La configurazione MkDocs vive nella root del repository:

mkdocs.yml

L'HTML generato da MkDocs viene prodotto in:

site/

La cartella site/ è un artefatto generato. Non deve diventare la fonte della documentazione e non deve essere modificata manualmente.

Accuratezza Dei Contenuti

La documentazione ufficiale deve descrivere funzionalità disponibili, riconoscibili nell'esperienza Drone Sky Check o realmente presenti nel repository.

Regole obbligatorie:

Regola	Applicazione
Non inventare funzionalità	Se una funzionalità non è disponibile, in beta, in sviluppo o pianificata in modo verificabile, deve essere omessa.
Verificare prima di scrivere	Ogni pagina deve essere allineata al comportamento reale dell'applicazione, dei servizi o dei documenti tecnici pertinenti.
Separare fatti e direzione futura	Le ipotesi non devono entrare nella documentazione ufficiale come promesse.
Non usare il README come fonte primaria	Il README.md può essere datato; usare codice, documentazione aggiornata e configurazione MkDocs.
Preservare gli URL	Cambiare titolo visibile quando serve, evitando modifiche agli slug pubblici se non indispensabili.

Stati Editoriali Delle Funzionalità

Quando si descrive lo stato di una funzione, usare internamente una delle seguenti classi.

Stato	Significato	Come comunicarlo agli utenti
AVAILABLE	Funzione realmente disponibile e utilizzabile.	Descrivere al presente o indicare "Disponibile".
BETA	Disponibile ma ancora in consolidamento.	Indicare "Beta", "in evoluzione" o "risultati dipendenti dai dati disponibili".
LIMITED_ACCESS	Disponibile solo per utenti, account o feature abilitate.	Indicare "Disponibile per account abilitati" o "Disponibile in DSC+".
IN_DEVELOPMENT	Codice o interfaccia in lavorazione, non ancora disponibile come esperienza stabile.	Indicare "In sviluppo" solo se serve orientamento.
PLANNED	Direzione futura non implementata.	Indicare "Direzione futura" o "prevista come evoluzione", senza date.

Questi codici non devono comparire necessariamente nelle pagine utente. Servono a mantenere coerenza editoriale.

Regola pratica:

• usare il presente per AVAILABLE, BETA e LIMITED_ACCESS;
• usare formule esplicite per IN_DEVELOPMENT e PLANNED;
• non scrivere "in futuro" quando è possibile indicare uno stato più preciso.

Struttura Delle Pagine Introduttive

Le pagine introduttive hanno responsabilità distinte.

Pagina	Responsabilità
Home	Spiega cos'è Drone Sky Check, cosa si può fare e da dove iniziare. Non contiene tabelle di avanzamento editoriale.
Panoramica del prodotto	Descrive lo stato attuale complessivo della piattaforma.
Visione del prodotto	Distingue fondazioni realizzate, funzioni in evoluzione e direzione futura.
Panoramica per l'utente	Orienta tra mappa, profilo, operatore e DSC+.

Queste pagine devono rimandare alle pagine di dettaglio invece di duplicarle.

Lingua E Terminologia

Tutta la documentazione deve essere scritta in italiano.

Usare accenti corretti:

Evitare	Usare
e'	è
puo'	può
qualita'	qualità
funzionalita'	funzionalità
modalita'	modalità

Possono rimanere in inglese:

• nomi ufficiali dell'interfaccia, per esempio Flight Log, Fleet Registry, Mission Planner, Flight Replay;
• nomi di moduli, endpoint, file, campi JSON e comandi;
• termini tecnici consolidati;
• nomi propri e citazioni dirette.

Presente E Futuro

Non usare il futuro per funzionalità già disponibili.

Evitare	Preferire
"Drone Sky Check permetterà..."	"Drone Sky Check permette..."
"DSC+ potrà introdurre inviti..." quando gli inviti sono implementati	"DSC+ consente inviti per account abilitati."
"Il Registro flotta arriverà..." quando è già documentato e presente	"Il Registro flotta è disponibile per account abilitati."

Per funzioni non disponibili usare:

• "È in sviluppo...";
• "Rientra nella direzione futura...";
• "È prevista come evoluzione, senza data pubblica confermata...".

Non inventare date di rilascio.

Documentazione Utente

Le pagine utente devono spiegare cosa vede e cosa può fare l'utilizzatore, prima di descrivere dettagli tecnici.

Devono:

• usare linguaggio naturale e professionale;
• indicare quando una funzione è disponibile solo in DSC+ o per account abilitati;
• spiegare limiti e responsabilità vicino alla funzione interessata;
• collegare alle pagine di dettaglio invece di ripetere interi paragrafi;
• evitare collection Firestore, UID tecnici, Cloud Functions e dettagli implementativi.

Documentazione Sviluppatore

Le pagine developer spiegano architettura, dati, API, integrazioni, sicurezza e manutenzione tecnica.

Possono documentare componenti beta, sperimentali o futuri quando servono a comprendere il progetto, ma devono dichiarare chiaramente:

• cosa è implementato;
• cosa è in sviluppo;
• cosa è direzione futura;
• quali moduli, endpoint o dataset reali sono coinvolti.

Criteri Per Documentare Una Funzionalità

Una funzionalità può essere documentata quando almeno una delle seguenti condizioni è soddisfatta:

• è presente nell'interfaccia in public/;
• è implementata in un modulo JavaScript del frontend;
• è esposta da una Cloud Function in functions/;
• è rappresentata da dataset presenti in public/data/ o functions/data/;
• è leggibile da un flusso Firestore usato dal prodotto;
• è descritta da un endpoint, helper o workflow implementato;
• è definita in roadmap o documentazione developer come direzione futura, senza essere presentata come disponibile.

Immagini E Screenshot

Le immagini devono trovarsi in:

docs/images/

Regole:

• riutilizzare screenshot esistenti quando sono ancora corretti;
• usare nomi file descrittivi e stabili;
• non referenziare immagini non presenti nel repository;
• evitare immagini decorative prive di valore informativo;
• inserire testo alternativo descrittivo;
• introdurre l'immagine con una frase che ne chiarisce il contesto;
• usare la sintassi Markdown di MkDocs Material con attr_list;
• usare di norma width="70%" o width="80%", evitando immagini a larghezza piena.

Per schemi di prodotto o architettura, preferire Mermaid quando rende bene nel tema. Se si usa SVG locale:

• inserire title e desc;
• evitare testo rasterizzato;
• verificare contrasto in tema chiaro e scuro;
• mantenere leggibilità su mobile.

Diagrammi Mermaid

I diagrammi Mermaid sono consigliati quando riducono ambiguità.

Usarli per:

• flussi utente;
• relazioni tra pilota, operatore, flotta e DSC+;
• pipeline dati;
• architettura frontend/backend;
• lifecycle account, membership o privacy.

Un diagramma non deve sostituire una spiegazione testuale essenziale.

Regole Anti-Duplicazione

Prima di creare o ampliare una pagina:

1. Cercare se l'argomento è già coperto.
2. Verificare se può essere aggiunto a una pagina esistente.
3. Creare una nuova pagina solo se ha un perimetro chiaro e stabile.
4. Aggiornare riferimenti incrociati solo verso pagine esistenti.

Le pagine devono avere responsabilità distinte. Una pagina utente su meteo, per esempio, non deve duplicare i dettagli tecnici del proxy METAR: deve rimandare alla pagina developer pertinente.

Manutenzione

La documentazione deve essere mantenuta con modifiche motivate da cambiamenti reali del prodotto o da una revisione editoriale esplicita.

Situazione	Azione corretta
Esiste già una pagina sull'argomento	Aggiornare la pagina esistente.
Una funzione cambia stato	Aggiornare stato, testo e link collegati.
Una informazione non è confermata	Rimuoverla o spostarla in una sezione di direzione futura, se pertinente.
Serve una nuova pagina	Crearla solo se l'argomento non ha una sede naturale.
Una pagina introduttiva diventa troppo tecnica	Spostare i dettagli nella sezione developer.

Evitare documentation churn: rinominare, spostare o riscrivere senza beneficio concreto rende la documentazione meno affidabile.

Verifiche Consigliate

Quando l'ambiente lo consente:

• eseguire mkdocs build --strict;
• verificare link interni;
• controllare titoli nel menu e breadcrumb;
• cercare forme ASCII come e', puo', qualita';
• cercare futuri impropri come sarà, permetterà, potrà, in futuro;
• confrontare lo stato dichiarato con codice, documentazione developer e roadmap;
• verificare che immagini e diagrammi siano leggibili in tema chiaro, scuro, desktop e mobile.

Non modificare dipendenze o configurazioni del progetto solo per forzare controlli non disponibili nell'ambiente locale.