Quartz 4

DOC-GUIDELINES

3 min read

DOC-GUIDELINES (Il Manifesto della Documentazione FIRE)

Versione: 1.0 Scopo: Definire lo standard di qualità, struttura e stile per la produzione di documentazione scientifica e operativa all’interno del progetto FIRE. Target dei Documenti: Trader Quantitativi, Sviluppatori, Analisti (Esperti o aspiranti tali).

1. La Filosofia: Partnership Tecnica

Non scriviamo per principianti che hanno bisogno di essere rassicurati. Scriviamo per professionisti (o aspiranti tali) che cercano competenza, precisione e velocità.

  • ❌ No Didattica Scolastica: Evitare toni da “maestrino” (“Ricordatevi che…”, “Come abbiamo visto prima…”).
  • ❌ No Marketing: Nessuna promessa di guadagno, nessun aggettivo superfluo (“Incredibile”, “Potente”).
  • ✅ Sì al Pragmatismo Scientifico: Fatti, numeri, limiti del modello, istruzioni.
  • ✅ Sì al “Pizzico Accademico”: Non aver paura di usare una formula matematica se spiega il concetto meglio di 100 parole. Conferisce autorità.

2. La Struttura Bipartita (Il “Metodo FIRE”)

Ogni documento relativo a un modulo funzionale (es. Forecast Lab, Scanner) DEVE seguire una rigida separazione tra teoria e pratica. Questo permette di isolare il sapere immutabile (Finanza/Matematica) dall’implementazione software (UI/Click).

📘 PARTE A: Il “Libro Quant” (Teoria)

  • Contenuto: Concetti puri, matematica, logica finanziaria. Agnostico dal software.
  • Stile: Accademico, Rigoroso, Definizioni formali.
  • Obiettivo: Spiegare il Perché e il Cosa.

🛠️ PARTE B: Il “Manuale Operativo” (Pratica)

  • Contenuto: Pulsanti, Menu, Flussi di lavoro, Settings. Specifico per FIRE.
  • Stile: Imperativo, Diretto, Sequenziale.
  • Obiettivo: Spiegare il Come.

3. Regole di Scrittura (Style Guide)

3.1. Istruzioni Operative (Algoritmi per Umani)

Mai usare la prosa per descrivere una sequenza di azioni. Usare liste numerate.

  • ❌ Cattivo: “Per iniziare l’analisi, dovresti andare nel menu e selezionare l’opzione…”
  • ✅ Buono:
    1. Apri il pannello Forecast Lab.
    2. Seleziona il modello TimesFM.
    3. Clicca Genera.

3.2. Definizioni e Metriche (Il “So What?“)

Mai definire una metrica senza dare le soglie di interpretazione operativa.

  • ❌ Cattivo: “L’RMSE è la radice dell’errore quadratico medio.”
  • ✅ Buono: “RMSE (Root Mean Squared Error): L’errore medio di prezzo nella valuta dell’asset.
    • Valore Basso: Modello preciso.
    • Valore Alto (es. > ATR): Modello inaffidabile per stop-loss stretti.”

3.3. Metafore e Linguaggio

  • Metafore: Solo se fanno risparmiare tempo (3 secondi vs 30 secondi). Altrimenti, usare il termine tecnico.
  • Rispettoso: Spiegare i termini tecnici la prima volta che appaiono, ma senza condiscendenza.
    • Esempio: “Il modello usa un’architettura Transformer Decoder-Only, simile a GPT, per…” (Spiega il contesto senza assumere ignoranza).

3.4. Pseudocodice come Lingua Franca

Il nostro lettore capisce la logica. Preferire lo pseudocodice alle lunghe descrizioni testuali delle strategie.

  • Esempio: 
    SE (Trend_Accuracy > 60%) E (RSI < 30):
    ENTRY: Long
ALTRIMENTI:
    Flat

4. Standard per le Risorse Visive

Ogni volta che si descrive una parte complessa della UI o un concetto astratto, è obbligatorio inserire un placeholder per l’immagine.

  • Sintassi: **[IMG-NOME-UNIVOCO]:** *Descrizione dettagliata di cosa deve mostrare l'immagine (es. 'Screenshot della Decay Curve con evidenziato il punto di flesso al 50%').*

5. Il Template Master (Struttura Obbligatoria)

Ogni Scientific Report deve seguire questo indice:

  1. Abstract: In 3 righe, cosa fa questo modulo.
  2. Fondamenti Teorici (Quant Book): I modelli, la matematica, le ipotesi.
  3. Integrità dei Dati: Come vengono trattati i dati (es. logica Full History vs Toolbar).
  4. Strumenti di Validazione (User Manual): Guida click-by-click alle Tab e ai controlli.
  5. Interpretazione dei Risultati: Come leggere i grafici. Casi studio (Successo vs Fallimento).
  6. Appendice Strategica: Esempi di pseudocodice per usare questi dati nel trading.

Graph View