I diagrammi di sequenza dovrebbero essere specifici o astratti?

I diagrammi dovrebbero aiutare a capire le cose .
Se non lo fanno, falliscono.

I diagrammi di sequenza sono molto bravi a spiegare i protocolli sulla rete e le interazioni singole in un'API, in qualsiasi API non banale avrai difficoltà a descrivere tutte le interazioni . (ad esempio non puoi )

Ovviamente devi fare più diagrammi , uno per ogni scenario di interazione , fare un singolo diagramma con tutte le interazioni sovrapposte l'un l'altro è malato e farà incrociare gli occhi della gente .

Dovrai comunque scrivere la tua documentazione in linguaggio naturale , comunque. I diagrammi possono solo aiutare a raggiungere una comprensione più ampia o più precisa in cima di una documentazione già ben scritta.

E se l'API implica l'utilizzo di oggetti diversi, di classi diverse, da utenti diversi, un diagramma di classe , può e sarà utile.

Dipende interamente da ciò che vuoi comunicare. Nella mia esperienza, i diagrammi di sequenza funzionano molto bene sia per i livelli molto alti che per i sistemi di livello molto basso.

Ad esempio, utilizziamo un diagramma di sequenza che mostra il flusso a livello di evento di un handshake SSL per aiutare a spiegare alcuni problemi di sicurezza agli utenti. Livello molto basso e molto concreto.

Usiamo anche un diagramma di sequenza che mostra lo scambio di messaggi ad alto livello nel nostro sistema distribuito tra i quattro o cinque attori sul posto. Ciò rende ogni attore qualcosa come 50.000 linee di codice in dimensioni - e gli eventi che richiedono più comunicazioni sono un "evento" in quella scala.