Skip to content

venetacucine.comDocumentazione di handover

Come funziona il sito, campo per campo, per chi lo eredita e deve metterci le mani senza averlo costruito.

Da dove partire

Se hai un problema e non sai ancora cosa lo produce, parti da Da un sintomo al documento: è organizzato per come i problemi arrivano, non per come il sito è fatto.

Se invece sai già cosa cerchi, l'indice completo raggruppa tutto per dominio: una pagina precisa sta nella sezione Pagine, un comportamento che vale su tutto il sito sta nei meccanismi condivisi, un problema del pannello di Craft o di un'integrazione esterna sta nei moduli backend.

Sopra a destra c'è la ricerca: indicizza il testo di tutti i documenti, e spesso è la via più veloce per trovare il campo o la funzione che stai cercando.

Com'è fatto ogni documento

Ogni documento risponde alle stesse sette domande, sempre nello stesso ordine:

  1. Cosa fa questa pagina?
  2. Com'è fatta?
  3. Da dove arrivano i dati?
  4. Quali campi del CMS la cambiano?
  5. Cosa può fregarti?
  6. Perché è così?
  7. Cosa condivide con altre pagine?

L'obiettivo dichiarato è far capire come ogni campo del backend altera il frontend, quindi il cuore di quasi tutti i documenti è la tabella dei campi: cosa cambia sul sito, e cosa succede se il campo resta vuoto.

La quinta domanda, "Cosa può fregarti?", raccoglie i comportamenti controintuitivi: è quella da leggere prima di toccare qualcosa.

Attenzione a come si legge: quella sezione elenca e non pesa. Registra il comportamento e va avanti, senza dire quanto sia grave né quanto spesso si presenti, quindi un difetto che richiede uno slug inventato a mano occupa lo stesso spazio di uno che colpisce tutti. Chi ne legge molte di fila ricava un'impressione più cupa della realtà. Il peso sta in Difetti noti del sito, dove le stesse voci hanno gravità, condizione di innesco e frequenza reale.

Cosa aspettarsi

  • I riferimenti al codice sono nella forma file:riga. Le righe si spostano: se non trovi quello che il documento dice, cerca l'identificatore vicino invece del numero.
  • I punti marcati [DA VERIFICARE] sono aperti: richiedono una prova nel pannello o in produzione, non si chiudono leggendo il codice.
  • La documentazione descrive come funziona il sito adesso. Non valuta le scelte di implementazione e non propone modifiche.

Materiale di progetto

Documenti di lavorazione, non di consegna: servono a chi continua a scrivere la documentazione.