Skip to main content
Questa documentazione è la fonte di verità unica per il team di delivery, quando impari qualcosa di nuovo, da un incidente, da una sessione di supporto Conduit o da un cliente, quel contenuto va qui, nel posto giusto, non in un nuovo file casuale. Una documentazione frammentata è peggio di nessuna documentazione: il team smette di fidarsi e comincia a tenersi le informazioni in privato.

​
Dove metto una cosa nuova

Prima di creare una pagina nuova, chiediti dove va il contenuto che hai in mano. Nella maggior parte dei casi esiste già la pagina giusta, va solo aggiornata.
Va nella pagina troubleshooting dell’integrazione giusta. Aggiungi una riga alla tabella esistente con il codice errore (o sintomo), la causa e la soluzione. Non creare una pagina “errori” separata, tienila vicina all’integrazione a cui appartiene.
Va nella sotto-pagina dell’integrazione corrispondente. Ad esempio, se hai capito come funziona la sincronizzazione della KB con Notion, la spiegazione va in Conduit → KB. Se riguarda la configurazione di uno smart lock, va in Shelly / SwitchBot → configurazione.
Va in Casistiche. Le casistiche sono procedure step-by-step per situazioni che si ripresentano (es. “ospite bloccato fuori”, “prenotazione non sincronizzata”, “link pagamento non arriva”). Se la stessa sequenza di azioni si ripete più di due volte, documentala lì.
Va in Best practice. Le best practice sono regole trasversali che non appartengono a una singola integrazione, sicurezza, comunicazione con gli studenti, gestione delle escalation, regole zero-segreti.
Crea un nuovo gruppo in docs.json seguendo il pattern delle integrazioni esistenti: aggiungi una panoramica e le sotto-pagine necessarie (configurazione, troubleshooting, tool/skill). Non inventare una struttura nuova, copia il pattern di un gruppo esistente (es. KrossBooking) e adattalo.

​
Come si pubblica

Ogni modifica alla documentazione segue questo flusso:
  1. Modifica il file .mdx corrispondente nel workspace
  2. Esegui il commit con un messaggio descrittivo (es. docs: aggiunto troubleshooting porta Shelly offline)
  3. Lancia git push origin main
  4. Mintlify effettua il deploy automatico, la modifica è live in pochi minuti
Se stai aggiungendo o rinominando pagine, aggiorna anche docs.json prima del push, altrimenti la pagina non compare nella sidebar anche se il file esiste.

​
Regole di stile

Segui queste regole per mantenere la documentazione coerente e leggibile anche per chi non ha un background tecnico.
  • Linguaggio plain, anche per i non-dev. Evita acronimi senza spiegazione e gergo tecnico non necessario. Se devi usare un termine tecnico, spiegalo la prima volta che compare.
  • Ogni troubleshooting = problema + soluzione. Non inserire mai solo il messaggio d’errore senza la soluzione. Una tabella incompleta è fuorviante.
  • Cita la fonte quando adatti contenuto esistente. Se la spiegazione è tratta da un runbook operativo o da una sessione di supporto, indicalo in nota, aiuta chi vuole approfondire a trovare il contesto originale.
  • Dettagli tecnici profondi (schemi API, payload) → linka il repo, non incollarli qui. La documentazione è una guida operativa, non un dump del codice. E soprattutto: non incollare mai secrets o chiavi, nemmeno di esempio.
Non creare pagine parallele sullo stesso tema. Se esiste già una pagina su “configurazione Shelly”, aggiorna quella, non aprirne un’altra con un titolo leggermente diverso. Le pagine duplicate causano confusione e vengono abbandonate: nel giro di settimane nessuno sa quale delle due è aggiornata.
La struttura di docs.json rispecchia esattamente la struttura della sidebar visibile nel portale. Se rinomini un file .mdx o sposti una pagina da un gruppo all’altro, aggiorna docs.json di conseguenza, altrimenti la sidebar mostra link rotti o voci fantasma.