Comunicazione dell'operazione prevista della logica di business dell'API per gli sviluppatori e gli uomini d'affari

Question

Comunicazione dell'operazione prevista della logica di business dell'API per gli sviluppatori e gli uomini d'affari

#1 da (2 voti)
#2 da (1 voti)

2

Attualmente sto progettando l'operazione prevista di un'API (RESTful) che un team di sviluppatori alla fine costruirà. Non mi occupo dei dettagli di implementazione, purché gli input siano mappati correttamente alle uscite (e i dati nel database non saranno incasinati :-)). Per me non è importante se è costruito in modo OOP o FP, per esempio.

Il problema : comunicare il funzionamento interno previsto / la logica aziendale dell'API in modo tale che gli uomini d'affari possano capire cosa sta succedendo (e si spera forniscano feedback) e che gli sviluppatori saranno in grado di scrivere cose che facciano quello che dovrebbe. Quindi, deve essere abbastanza astratto, ma deve ancora contenere abbastanza dettagli per gli sviluppatori.

Le specifiche sono pensate principalmente per essere consumate dagli sviluppatori. Gli uomini d'affari dovrebbero essere in grado di capirli, ma è fondamentale che contengano abbastanza informazioni per consentire agli sviluppatori di iniziare a costruire.

Con ogni mezzo, immagino che abbia senso descrivere ogni interazione dell'utente (o endpoint dell'API) separatamente. Potrebbero essere descritti approssimativamente nel seguente formato:

Descrizione (ad esempio "creazione di un account utente")
Parametri di input (dati che devono essere forniti dall'utente, ad esempio "nome", "e-mail" e "password")
Processo (una sorta di rappresentazione dei meccanismi interni e dei risultati)

Ha senso? Mi mancano cose importanti qui?

Quale sarebbe il formato più adatto per rappresentare il processo?

Lo pseudocodice non ha molto senso per gli uomini d'affari. Verranno scritti test automatici (e utilizzati dagli sviluppatori) ma gli imprenditori non li leggeranno.

Attualmente, mi sto appoggiando ai diagrammi di flusso. Sono di natura visuale, abbastanza facili da capire se fatti bene e in grado di contenere la quantità di dettagli richiesta (come i condizionali). È possibile fare riferimento alle entità e agli attributi dell'ERR che verranno archiviati in Confluence (il nostro sistema di documentazione). Le annotazioni possono essere utilizzate per fornire ulteriori dettagli (tecnici).

È un approccio ragionevole? I diagrammi di flusso sono una soluzione decente in questa situazione? Qualche opzione migliore?

design specifications documentation business-logic flowchart

posta Willem-Aart 21.06.2018 - 21:17

fonte

2 risposte

Leggi altre domande sui tag design specifications documentation business-logic flowchart

La mia architettura a tre livelli è ben implementata? Qual è la complessità di trovare e controllare i numeri primi?

score 2 · Answer 1

Il corretto o il "migliore" significa descrivere la funzionalità di un'API dipende dalla funzionalità specifica, per questo non esiste una soluzione "taglia unica per tutti".

Per alcune funzionalità, i diagrammi di flusso possono essere una buona opzione. Per alcuni, i diagrammi del flusso di dati potrebbero essere migliori. Organizzare le descrizioni dei processi in termini di "input, processing, output" è una tecnica molto antica, ma comunque molto efficace. Per alcuni aspetti, una scelta rappresentativa di esempi servirà meglio - il secondo potrebbe anche essere inserito in "storie di utenti". E le tabelle con attributi (e forse datatype) saranno comprese anche dagli sviluppatori e dagli utenti esperti. Alcuni utenti potrebbero persino capire i modelli ER (ma attenzione, la normalizzazione può essere già troppo tecnica per diversi utenti).

"Domain Driven Design" tenta di affrontare il problema creando un linguaggio ubiquitario , un linguaggio con meno ambiguità e semantica chiara per gli sviluppatori e degli utenti - anche questa è una buona idea per determinati domini, se stai facendo DDD o no.

Ma alla fine, hai bisogno di qualche anno di esperienza per descrivere la funzionalità in modo preciso, trovando il giusto livello di astrazione per il tuo pubblico, usando un linguaggio naturale che non sia troppo sciatto e non troppo formale. Questo è qualcosa che non puoi semplicemente imparare dai libri o da una risposta qui su questo sito, è necessario esercitarsi.

Quasi dimenticato - Joel Spolsky ha scritto un bel post sul blog 18 anni fa su come scrivere le specifiche funzionali . Questo è probabilmente un buon esempio per ciò che hai chiesto. Per citare la sua introduzione:

A functional specification describes how a product will work entirely from the user’s perspective. It doesn’t care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on.

quindi evita di concentrarti sui "meccanismi interni" (come ha scritto anche @RobertHarvey nel suo commento). Concentrati su cosa fa una funzione, non come .

score 1 · Answer 2

Penso che tu stia ancora pensando come uno sviluppatore o un architetto, e devi pensare più come un utente / product manager / analista di business.

Puoi descrivere il funzionamento dell'API in termini di storie utente o casi d'uso? Questi sono meno tecnici ma hanno un impatto elevato se eseguiti correttamente.