Dove si trovano le descrizioni dell'interfaccia in una specifica?

Se sei rigoroso nella tua interpretazione dei tre livelli, una dichiarazione dell'interfaccia in quanto tale andrebbe nel livello intermedio, ma si "estenderebbe" ai livelli sopra e sotto, in questo modo:

Requirement

The ability to export data X into external system Y.

Functional spec

Data export will go through a REST interface with the following endpoints:

...

Design spec

REST interfaces will be implemented via library X, calling services Y...

Questo sarebbe lo stesso sia che tu definisca l'interfaccia o ne usi una già esistente (come un formato di file di terze parti), ma se la dichiarazione dell'interfaccia è già disponibile esternamente, ti riferirai semplicemente alle specifiche funzionali, piuttosto che duplicarlo.

Quanto sopra si applica solo alle interfacce esterne, le interfacce interne tra le diverse parti dello stesso sistema sarebbero meglio definite nelle specifiche di progetto.

Ma alla fine ciò che dovresti pensare (come con qualsiasi documentazione) è questo: come verrà usata questa documentazione? Chi è il target di riferimento? Dove mi aspetto che un lettore ragionevole cerchi le specifiche dell'interfaccia?

Un altro modo per giustificare la specificazione di questo a livello funzionale è pensare a chi sei responsabile se stai per cambiare qualcosa.

1. Se si modifica qualcosa specificato nelle specifiche di progettazione, questa dovrebbe essere la questione interna dell'applicazione. Tecnicamente nessuno dovrebbe saperlo. Se il tuo sistema supera tutti i test di integrazione, stai bene.
2. Se apporti una modifica a qualcosa nelle specifiche funzionali, dovresti notificare a tutti gli utenti la funzione che intendi modificare, inclusi i sistemi esterni che si collegano ai tuoi.
3. Se apporti una modifica al livello dei requisiti ... beh, non dovresti, è compito dell'azienda impostare i requisiti.

Questo sembra abbastanza soggettivo. Personalmente inserirò le descrizioni dell'interfaccia nelle specifiche funzionali (perché sono "requisiti" piuttosto che "decisioni"), o in un documento separato "appendice" che non si trova affatto su questa scala. Ma si adattano altrettanto facilmente alle specifiche di progettazione (perché sono dettagli di implementazione). È difficile rispondere a questo - che, suppongo, è il motivo per cui l'hai chiesto.

La risposta diretta alla tua domanda, però, è che non è un modo "ufficiale" per farlo.

Avevamo un sistema di documentazione simile per una grande azienda di soluzioni informatiche per cui ho lavorato.

I dettagli che hai descritto correttamente si trovano nelle specifiche di progettazione a mio avviso, se non in un livello inferiore a questo.

Per riassumere il motivo, questa è la mia opinione su quei livelli di specifiche:

Requisiti

Definisce ciò che è richiesto ad un livello elevato. Le regole aziendali se ti piacciono.

Specifiche funzionali

Descrive ad alto livello le parti del sistema che forniranno i requisiti.

Specifiche di progettazione

Descrive il dettaglio (cioè il "come") - gli interni del sistema, il design logico del DB, il design fisico del DB. Tutto ciò che richiede una suddivisione ulteriormente va in un documento / specifiche di progettazione al di sotto di questo.

Come hai già delineato, vuoi evitare di dover spingere i dettagli verso l'alto attraverso i livelli della documentazione. Se si spinge il dettaglio nelle specifiche di progettazione, questo di solito è soddisfacente, ma ci sono ovviamente dei momenti in cui vi è un cambiamento fondamentale che richiede modifiche attraverso il progetto. Succede: le persone dimenticano / fraintendono i requisiti o i pezzi vengono aggiunti e rimossi.

Ci sono alcuni modi per gestirlo, ma tendono a non far parte di una specifica di requisiti o di una specifica di progettazione. Ciò è particolarmente vero se si sta costruendo il software internamente, ma è necessario rilasciare la documentazione dell'interfaccia a un pubblico più ampio. Probabilmente non vuoi rilasciare tutti i tuoi requisiti software e le informazioni di progettazione interna a entità esterne interessate alle tue interfacce.

Al lavoro, utilizziamo le specifiche dei requisiti di interfaccia (oi documenti dei requisiti dell'interfaccia) e le specifiche di controllo dell'interfaccia (o documenti di controllo dell'interfaccia ). Le specifiche dei requisiti di interfaccia tendono a esistere solo a livello di sistema o sottosistema. Nel momento in cui si ha a che fare con un componente solo software, i requisiti dell'interfaccia sono stati definiti, quindi includeremo solo le informazioni pertinenti dalle specifiche di livello superiore (inclusione o traccia - entrambe sono facili con uno strumento di gestione dei requisiti).

Il vantaggio di questo è che tendiamo a non rilasciare le specifiche dei componenti (requisiti o design) a parti esterne. Le specifiche dei requisiti del software contengono requisiti richiesti dall'azienda per supportare gli obiettivi di sviluppo tecnologico a lungo termine e i clienti interni dall'ingegneria dei sistemi, SQA, produzione e altri. Questi sono requisiti che potremmo non voler esporre a clienti esterni per una serie di motivi (in particolare vincoli o requisiti a supporto dello sviluppo tecnologico a lungo termine).

La specifica di controllo dell'interfaccia o il documento di controllo dell'interfaccia fornisce semplicemente una specifica per gli ingressi e le uscite tra due o più componenti, sottosistemi o sistemi. Come scriviamo questi varia. Per alcuni prodotti, un componente emette un formato standard, quindi abbiamo un ICD per quel formato e un ICD separato per l'input. Possiamo quindi andare a assemblare questi pezzi in diversi modi per i clienti, creando una sorta di volume di documenti tutti collegati tra loro.

Qualcos'altro da tenere a mente, un documento non deve necessariamente essere un documento Microsoft Word o PDF. Una pagina wiki o una raccolta di pagine wiki (con controllo di modifica e cronologia delle revisioni appropriati, in particolare con la possibilità di esportare in un formato statico) è tanto un documento quanto gli altri formati. È più importante che il contenuto sia disponibile e collegato in modo appropriato in modo significativo rispetto al modo in cui è alla fine unito.

La progettazione e il controllo dell'interfaccia è una pratica dell'Ingegneria dei sistemi. La NASA ha un documento interessante sull'argomento . Tuttavia, a seconda del campo, è probabilmente eccessivo. Potresti essere in grado di imparare da queste pratiche e adattarle ad un livello appropriato.