Come documentare gli URL e l'interazione tra le pagine

6

Stiamo sviluppando un'applicazione web che sta ora crescendo fino a poche pagine, tutte con dati complessi e interazioni piuttosto complesse tra le pagine.

Ad esempio, il flusso di accesso comprende le seguenti diverse richieste possibili ai nostri controllori:

  • Accedi - > Hai dimenticato la password - > Invia email [solo POST] - > Token di reimpostazione della password - > Nuova password invia - > Torna al Login
  • Accedi - > Crea nuovo utente - > Registrati [solo POST] - > Invia email di attivazione
  • Accedi - > Elabora nuove richieste di invito - > Pagina principale

... e un paio di altre varianti, tutte incluse l'invio di e-mail, che richiedono i token di verifica / attivazione; e questo non inizia nemmeno a sfiorare le molteplici pagine di tipo wizard per la connessione a applicazioni esterne e così via.

Esiste un buon modo per documentare tutti questi URL diversi, i loro parametri e i modi in cui questi interagiscono tra loro? Per applicazioni Web complesse, avere un modo per fare riferimento a tutte queste diverse richieste deve essere una risorsa piuttosto buona ... E soprattutto in termini di sicurezza, essere in grado di ispezionare visivamente il flusso di richieste e individuare potenziali problemi. (Ehi, perché questa pagina è GET? Dovrebbe essere un POST con protezione CSRF!)

Semplicemente non mi sento come se un documento Word fosse abbastanza ... UML? xmldoc?

Non è importante, ma è scritto in C #.

    
posta mgefvert 30.10.2016 - 03:31
fonte

3 risposte

1

A volte un'immagine vale più di mille parole. Creo una sorta di Diagramma di stato o un diagramma di flusso.

Immagine via Mirosamek in Wikipedia inglese

    
risposta data 30.10.2016 - 11:21
fonte
1

Non esiste un diagramma UML specifico per la navigazione dell'interfaccia utente. Tuttavia, potresti "adottare" alcuni di quelli esistenti.

Diagramma di stato come RubberDuck come menzionato o Diagramma di attività come suggerito da IBM.

I diagrammi di stato sono utili per disegnare panoramiche . I diagrammi di attività potrebbero essere utilizzati per approfondire i dettagli di ogni stato.

    
risposta data 30.10.2016 - 11:49
fonte
0

Ci sono molte cose che puoi fare.

Prima di tutto, è possibile che in realtà si suppone di ricevere una grossa parte di questa documentazione, non di produrla. Rivolgiti al team manager o al PM che sta producendo analisi e documenti architettonici.

Se non hai avuto successo con questo tentativo, c'è tutta la disciplina di analisi di fronte a te. Vorrei semplicemente indirizzare i tuoi punti dolenti.

  • La maggior parte delle volte gli URL non interagiscono tra loro. È un utente che esegue alcuni pulsanti di selezione dello scenario e richiede URL. Un buon modo per documentare tutto questo è iniziare con casi d'uso relativi all'interazione tra utenti e sito web e ai flussi di schermo.
  • URL e servizi sono soggetti a modifiche. Non impazzire riscrivere tutto crea strati di documentazione.
    • Obiettivo per utente. Come l'utente interagisce con l'applicazione, indipendentemente dall'implementazione.
    • Per interazione dell'utente con il sistema. In che modo ogni richiesta dell'utente viene soddisfatta dai metodi web rivolti al browser, quali parametri e richieste vengono utilizzati.
    • Per metodo. Come ogni metodo fa il suo lavoro interagendo con db e altri metodi di back-end.
  • Non è necessario creare diagrammi UML per tutto, ma la mia ipotesi è che si possa trovare utile avere un diagramma di sequenza per interazione utente / pagina / schermo e diagramma di attività per metodo.
  • Crea un catalogo esauriente di metodi / servizi, compresi tutti gli URL, i nomi e i parametri. Ma non il loro uso e la logica dietro.
  • Per "avere un modo per fare riferimento a tutte queste diverse richieste", introdurre una riconciliazione tra il catalogo, la documentazione e le fonti. Dipende in gran parte dallo strumento che stai usando, inizia con le pagine wiki per metodo e link tra loro se non hai nulla.
  • Per gestire il grado di complessità separare gli scenari principali (Login - > Pagina principale) da alternative (password dimenticata, registrazione, tentativo di accesso fallito). Per non travolgere le alternative del lettore possono essere isolate l'una dall'altra e gli scenari principali in gruppi per area.
risposta data 31.10.2016 - 10:06
fonte

Leggi altre domande sui tag