Drone Sky Check Documentation Guidelines

Questo documento definisce le regole per costruire e mantenere la documentazione ufficiale di Drone Sky Check.

In questa fase non contiene la documentazione del prodotto: stabilisce l'infrastruttura editoriale, la struttura proposta e le regole operative da seguire nei prossimi interventi.

Ambito della documentazione

La documentazione del progetto deve essere sviluppata nella cartella:

docs/

Il file di configurazione MkDocs, quando verra' introdotto, dovra' trovarsi nella root del progetto:

mkdocs.yml

L'HTML generato da MkDocs dovra' essere prodotto nella cartella di output standard:

site/

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

Per il momento non devono essere creati altri file Markdown oltre a questo documento.

Fonte di verita'

Il codice e' la fonte principale della documentazione.

Ogni documento futuro deve essere scritto solo dopo aver ispezionato il codice relativo alla funzionalita' descritta. La documentazione esistente, inclusi documenti di altri progetti come Mini Tracker, puo' essere usata come riferimento stilistico e organizzativo, ma non come fonte funzionale per Drone Sky Check.

Regole obbligatorie:

Regola	Applicazione
Non inventare funzionalita'	Se una funzionalita' non e' verificabile nel codice, deve essere omessa.
Verificare prima di scrivere	Ogni pagina deve nascere dall'ispezione dei file pertinenti in public/ e functions/.
Citare concetti reali del progetto	Nomi di moduli, dati, endpoint e workflow devono riflettere il codice effettivo.
Separare fatti e ipotesi	Le ipotesi non devono entrare nella documentazione ufficiale.
Non usare il README come fonte primaria	Il README.md e' datato e potra' essere aggiornato solo in una fase successiva.

Architettura osservata

La struttura futura della documentazione deve tenere conto dell'architettura realmente presente nel codice:

Area	Evidenza nel codice	Impatto documentale
Frontend statico/PWA	public/index.html, public/service-worker.js, public/manifest.webmanifest	Documentare interfaccia, comportamento offline/cache, installazione e limiti della PWA solo dopo verifica puntuale.
Mappa interattiva	Moduli Leaflet in public/js/, layer e pannelli CSS	Documentare dashboard, mappa, layer e strumenti utente.
Dati geografici	public/data/, functions/data/, file GeoJSON e JSON arricchiti	Documentare formato, origine, aggiornamento e uso dei dataset.
API pubbliche	functions/api/zoneCheckV2.js, functions/api/zones.js, public/api/	Documentare endpoint, parametri, risposte, sicurezza e casi d'uso.
Cloud Functions Firebase	functions/index.js e sottocartelle pubbliche collegate al prodotto	Documentare backend, funzioni esportate, runtime Node 20 e integrazioni pubbliche.
Firestore	Moduli traffico, tracker, statistiche e layer realtime	Documentare raccolte e flussi solo dopo ispezione dei punti di scrittura e lettura.
NOTAM e METAR	notamProxy, metarProxy, helper NOTAM/METAR frontend	Documentare dati aeronautici, proxy, cache e limiti operativi.
Traffico e tracking	Moduli public/js/drones/, public/js/air/, functions/traffic/, functions/trackers/	Documentare Drone Tracking, Air Traffic, receiver e heartbeat.
Pianificazione e autorizzazioni	public/js/waypoint/, public/js/authorization/, functions/authorization/	Documentare flight planning e workflow autorizzativi solo se confermati dal codice.
Meteo e sole	public/js/metar/, public/js/tools-weather-wind.js, public/js/sun/	Documentare meteo, METAR, vento e strumenti solari come sezioni operative distinte.
3D airspace	public/airspace3d/, public/js/airspace3d/, public/preview3d/	Documentare viste 3D e preview solo dopo verifica delle interazioni reali.
AI	functions/ai/, public/js/ai/	Documentare analisi AI, input, output e limiti con linguaggio tecnico, non promozionale.

Struttura generale proposta

La documentazione dovra' essere organizzata in sezioni distinte per pubblico e scopo. La struttura definitiva andra' confermata pagina per pagina durante l'ispezione del codice.

Sezioni generali

• Product Overview
• Product Vision
• Release Notes
• Glossary

Lingua della documentazione

Tutta la documentazione deve essere scritta in italiano.

Questa regola si applica a:

• nuova documentazione;
• aggiornamenti della documentazione esistente;
• esempi di codice;
• tabelle;
• didascalie delle figure;
• diagrammi Mermaid.

Anche quando i prompt o le richieste dell'utente sono scritti in un'altra lingua, la documentazione generata deve essere interamente in italiano.

Possono rimanere nella lingua originale solo il codice sorgente, i nomi dei file, gli endpoint API, i campi JSON, i comandi da riga di comando, le etichette dell'interfaccia utente, i nomi propri e le citazioni dirette, quando appropriato.

Funzionalita' Sperimentali E Integrazioni Non Pubbliche

La documentazione ufficiale deve descrivere esclusivamente funzionalita' pubbliche, rilasciate e destinate agli utilizzatori del prodotto.

Non devono essere documentati:

• moduli sperimentali;
• funzionalita' in sviluppo;
• integrazioni non ancora pubbliche;
• modalita' di test o debug;
• feature flag utilizzate solo durante lo sviluppo;
• endpoint o pannelli riservati ai test.

La presenza di codice nel repository non implica che una funzionalita' debba essere documentata. Anche se una funzione, una cartella, un endpoint o un'integrazione sono presenti nel codice, devono essere ignorati finche' non fanno parte ufficialmente del prodotto.

Esempi tipici:

• modalita' beta;
• pannelli di debug;
• configurazioni di sviluppo;
• integrazioni con sistemi di terze parti non ancora rilasciate.

Documentazione utente

Le pagine utente devono spiegare cosa vede e cosa puo' fare l'operatore, prima di descrivere dettagli tecnici.

Struttura proposta:

• Dashboard
• Mappa
• NOTAM
• Zone di volo
• Infrastrutture aeronautiche
• Drone Tracking
• Air Traffic
• Flight Planning
• Meteo
• Aree operative UAS e autorizzazioni
• Vista 3D dello spazio aereo
• Settings
• FAQ
• Troubleshooting

Ogni pagina utente deve includere solo funzionalita' effettivamente presenti nell'interfaccia o nei moduli caricati dal frontend.

Documentazione tecnica

Le pagine developer devono spiegare come il sistema e' costruito, quali dati usa, quali API espone e quali vincoli di manutenzione esistono.

Struttura proposta:

• Architecture
• Backend
• Frontend
• Database
• GeoJSON
• Data Sources
• Update System
• APIs
• Cloud Functions
• Firestore Collections
• Traffic Ingestion
• Tracker Heartbeat
• AI Integration
• Coding Guidelines
• Roadmap

La documentazione tecnica deve separare chiaramente:

• frontend statico in public/;
• backend Firebase Cloud Functions in functions/;
• dataset statici e generati;
• integrazioni esterne;
• logica condivisa di analisi delle zone.

Regole di scrittura

La documentazione deve usare uno stile da documentazione tecnica ufficiale.

Deve:

• evitare linguaggio marketing;
• usare frasi chiare, verificabili e sobrie;
• distinguere documentazione utente e documentazione developer;
• spiegare prima i concetti operativi e poi quelli implementativi;
• indicare prerequisiti, limiti e responsabilita' quando rilevanti;
• usare tabelle quando migliorano la leggibilita';
• usare diagrammi Mermaid quando aiutano a chiarire flussi, architettura o relazioni fra componenti;
• preferire esempi brevi e realistici a descrizioni generiche;
• mantenere coerenza nei nomi di funzionalita', file, endpoint, layer e dataset.

Non deve:

• promettere funzioni non dimostrate dal codice;
• trasformare note interne o commenti temporanei in documentazione ufficiale;
• copiare testi datati senza verifica;
• duplicare la stessa spiegazione in piu' pagine;
• usare screenshot, endpoint o nomi di file non esistenti.

Ordine consigliato delle informazioni

Ogni pagina futura dovrebbe seguire questo ordine, adattandolo al contenuto:

1. Scopo della funzionalita'.
2. Quando usarla.
3. Cosa vede o riceve l'utente.
4. Flusso operativo principale.
5. Dati utilizzati.
6. Limiti e casi particolari.
7. Dettagli implementativi, se la pagina e' tecnica.
8. Riferimenti a pagine correlate, evitando duplicazioni.

Immagini e screenshot

Le immagini della documentazione devono trovarsi in:

docs/images/

Le sottocartelle devono essere dedicate agli argomenti documentati. Esempi:

docs/images/dashboard/
docs/images/map/
docs/images/notam/
docs/images/flight-planning/
docs/images/meteo/
docs/images/api/
docs/images/architecture/

Regole per le immagini:

• riutilizzare screenshot esistenti quando sono ancora corretti;
• salvare le immagini vicino all'argomento che descrivono;
• usare nomi file descrittivi, stabili e in minuscolo;
• non referenziare mai immagini non presenti nel repository;
• aggiornare uno screenshot solo se l'interfaccia o il comportamento documentato sono cambiati;
• evitare immagini decorative prive di valore informativo.

Ogni immagine deve supportare una spiegazione specifica. Se una sezione e' comprensibile senza screenshot, l'immagine non e' obbligatoria.

Diagrammi Mermaid

I diagrammi Mermaid sono consigliati per:

• flussi API;
• pipeline di aggiornamento dati;
• relazione tra frontend, Cloud Functions, Firestore e fonti esterne;
• workflow di pianificazione o autorizzazione;
• lifecycle di traffico, tracker e receiver.

Un diagramma deve essere aggiunto solo quando riduce ambiguita'. Non deve sostituire una spiegazione testuale essenziale.

Manutenzione

La documentazione deve essere mantenuta con modifiche minime e motivate da cambiamenti reali del codice.

Regole di manutenzione:

Situazione	Azione corretta
Esiste gia' una pagina sull'argomento	Aggiornare la pagina esistente.
La pagina e' incompleta	Estenderla, evitando riscritture totali non necessarie.
Una funzionalita' cambia nel codice	Aggiornare solo le sezioni interessate.
Un'informazione non e' piu' verificabile	Rimuoverla o marcarla come da verificare solo in bozze interne, non nella documentazione ufficiale.
Serve una nuova pagina	Crearla solo se l'argomento non ha una sede naturale in pagine esistenti.

Deve essere evitato il documentation churn: rinominare, spostare, riscrivere o riorganizzare documenti senza un beneficio concreto rende la documentazione meno affidabile.

Regole anti-duplicazione

Prima di creare un nuovo documento:

1. Cercare se l'argomento e' gia' coperto.
2. Verificare se puo' essere aggiunto a una pagina esistente.
3. Creare una nuova pagina solo se ha un perimetro chiaro e stabile.
4. Aggiornare eventuali riferimenti incrociati solo quando il documento esiste davvero.

Le pagine devono avere responsabilita' distinte. Per esempio, una pagina utente su "Meteo" non deve duplicare i dettagli tecnici del proxy METAR; deve rimandare alla pagina tecnica appropriata quando questa sara' disponibile.

Convenzioni editoriali

• Lingua principale: italiano.
• Titoli: brevi, descrittivi, coerenti con la navigazione.
• Codice, nomi file, endpoint e campi JSON: sempre in monospace.
• Tabelle: usare quando confrontano dati, endpoint, stati, layer o responsabilita'.
• Avvisi e limiti: inserirli vicino alla funzionalita' a cui si riferiscono.
• Link interni: aggiungerli solo verso pagine gia' esistenti.
• Terminologia aeronautica: usare termini coerenti con il codice e con le fonti dati effettivamente integrate.

Criteri per documentare una funzionalita'

Una funzionalita' puo' essere documentata solo quando almeno una delle seguenti condizioni e' soddisfatta:

• e' presente nell'interfaccia in public/;
• e' implementata in un modulo JavaScript del frontend;
• e' esposta da una Cloud Function in functions/;
• e' rappresentata da dataset effettivamente presenti in public/data/ o functions/data/;
• e' leggibile da un flusso Firestore verificato nel codice;
• e' descritta da un endpoint, helper o workflow implementato.

Se il codice contiene file con nomi sperimentali, non usati o commentati, la relativa funzionalita' deve essere documentata solo dopo aver verificato che sia effettivamente caricata o richiamata.

Stato iniziale

Questo file e' il punto di partenza dell'infrastruttura documentale di Drone Sky Check.

I prossimi passi dovranno creare i documenti effettivi uno alla volta, sempre partendo dall'ispezione del codice e senza modificare il README.md fino a quando la documentazione principale non sara' sufficientemente completa.

Evoluzione della documentazione

La documentazione deve evolvere insieme al progetto.

Se durante l'ispezione del codice emerge una struttura piu' adatta di quella inizialmente prevista, e' consentito aggiornare l'organizzazione della documentazione, purche' la modifica sia motivata, coerente e mantenga la stabilita' dei documenti gia' esistenti.