Documentazione e ADR

Archyl fornisce potenti funzionalità di documentazione che ti permettono di creare documentazione ricca e collegata insieme ai tuoi diagrammi architetturali. Mantieni le tue conoscenze architetturali organizzate e connesse.

Creare Documentazione

Documentazione Manuale

Per creare documentazione manualmente:

1. Vai alla scheda Docs nel tuo progetto
2. Clicca su Nuovo Doc
3. Inserisci un titolo e scrivi il contenuto in Markdown
4. Aggiungi tag per l'organizzazione
5. Clicca su Salva

La documentazione supporta la sintassi Markdown completa inclusi:

• Intestazioni e formattazione
• Blocchi di codice con evidenziazione sintassi
• Tabelle e liste
• Immagini e link

Importazione da Git

Puoi importare documentazione esistente dal tuo repository Git:

1. Vai su Impostazioni Progetto > Scoperta Documentazione
2. Configura la connessione al repository
3. Clicca su Scopri Docs
4. Revisiona e approva la documentazione scoperta

Perfetto per importare file README esistenti, specifiche tecniche o contenuti wiki.

Collegamento agli Elementi Architetturali

La documentazione diventa più potente quando collegata alla tua architettura:

Creare Collegamenti

1. Apri una pagina di documentazione
2. Clicca su Collega a Elemento
3. Cerca o sfoglia l'elemento architetturale
4. Seleziona gli elementi da collegare
5. Clicca su Fatto

Visualizzare la Documentazione Collegata

Quando visualizzi un elemento nel diagramma, la documentazione collegata appare nel pannello dettagli. Questo fornisce contesto immediato senza lasciare la vista del diagramma.

Casi d'Uso per il Collegamento

• Collegare documentazione API ai container di Servizi
• Collegare guide di setup ai componenti infrastrutturali
• Collegare specifiche di design ai contesti di sistema
• Collegare commenti del codice agli elementi Codice

Architecture Decision Record (ADR)

Gli ADR documentano decisioni architetturali importanti con il loro contesto e le loro conseguenze.

Cos'è un ADR?

Un Architecture Decision Record cattura:

Creare un ADR

1. Vai alla scheda Decisioni nel tuo progetto
2. Clicca su Nuovo ADR
3. Compila i campi dell'ADR
4. Collega agli elementi architetturali pertinenti
5. Clicca su Salva

Flusso di Lavoro degli ADR

Gli ADR seguono un ciclo di vita:

1. Proposto: Bozza iniziale, in discussione
2. Accettato: La decisione è stata presa e approvata
3. Deprecato: Non più rilevante ma conservato per lo storico
4. Sostituito: Rimpiazzato da una decisione più recente

Scoperta degli ADR

Come la documentazione, anche gli ADR possono essere scoperti dal repository:

1. Vai su Impostazioni Progetto > Scoperta ADR
2. Configura il percorso dei tuoi ADR (es. docs/adr/)
3. Clicca su Scopri ADR
4. Revisiona e approva i record scoperti

Best Practice

Mantieni la Documentazione Aggiornata

• Aggiorna i docs quando l'architettura cambia
• Revisiona la documentazione durante le retrospettive di sprint
• Usa gli ADR per decisioni significative

Collega Tutto

• Ogni sistema dovrebbe avere un doc descrittivo
• Collega gli ADR ai componenti interessati
• Fai riferimenti incrociati nella documentazione correlata

Usa i Tag Efficacemente

• Tag per dominio (auth, pagamenti, ecc.)
• Tag per tipo (api, guida, specifica)
• Tag per stato (bozza, revisione, finale)

Linee Guida per gli ADR

• Crea ADR per decisioni significative
• Includi le alternative considerate
• Documenta i trade-off
• Collega alle PR di implementazione quando possibile

Impostazioni di Scoperta della Documentazione

Configura come viene scoperta la documentazione:

Pattern di Percorso

Specifica quali percorsi scansionare:

docs/
wiki/
README.md
*.md

Pattern di Esclusione

Salta determinati file:

node_modules/
vendor/
CHANGELOG.md

Prossimi Passi

• Scoperta Potenziata dall'AI - Scoprire automaticamente l'architettura
• Condivisione e Incorporamento - Condividere la documentazione esternamente
• Esportazione - Esportare la documentazione con i diagrammi