Come devo documentare un'applicazione multilivello?

Question

Come devo documentare un'applicazione multilivello?

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

1

Devo creare una struttura di documentazione per un'applicazione legacy e non sono sicuro di come organizzarlo. Obiettivi della documentazione :

Elenco dei casi d'uso
Flusso del programma per ciascuno dei casi d'uso. ( Diagramma di flusso di tutti i passaggi logici che il codice esegue per un particolare caso d'uso ).
Per quanto possibile le spiegazioni di perché viene seguita una determinata logica di business / codice.
Il formato della documentazione, se possibile, non dovrebbe richiedere l'installazione di un nuovo strumento e, nel migliore dei casi, può essere letto in formato Word o PDF (in modo che i tipi di attività possano verificarlo facilmente).
Alcune domande che dovrebbero essere risolte utilizzando la documentazione: "Quale logica aziendale esegue il codice per un determinato caso d'uso?"; "Il codice è ridondante altrove nell'applicazione?"; "Se cambio questo codice, quali casi d'uso sono interessati?";

Caratteristiche dell'applicazione : (è generalmente un po 'caotico, con la presentazione e la logica di business leggermente mescolate in quasi tutti i livelli)

Presentazione in Web Form .NET mediante WebControls (GridViews, ObjectDataSource, Reports) e JavaScript (jQuery, jQuery-ui) nelle pagine * .aspx
Codice lato server in C # in * .aspx.cs per gestire gli eventi post-back.
C # Code-Pages e un progetto separato integrato nella WebApplication che fornisce Business Logic come parte dell'applicazione Web
SQL Server per la persistenza dei dati (DB dati master, DB di gestione temporanea dati)
Visualizzazioni che includono alcuni dati di altri server
Assemblaggi CLR C # per la business logic implementata su SQL Server e alcune stored procedure / trigger SQL minori
Una struttura di file sullo stesso server del DB SQL che gestisce l'archiviazione, l'importazione dei dati dai file.
Interfaccia file per SAP (che non comprendo ancora completamente).

Finora ... ho iniziato a documentare in Word. Ho un file Word separato per il front-end e la struttura del database / file. Comincio ogni file con Use-Case (i processi avviati dall'utente sono in front-end e pianificati nel file Database), seguiti dalla struttura del codice. Ogni caso d'uso ha un collegamento ipertestuale a un diagramma di flusso / spiegazione del codice che viene eseguito per primo, che ha un collegamento ipertestuale al diagramma di flusso / spiegazione del codice che verrà eseguito successivamente, ecc ... Lo faccio in modo che ogni parte del codice sia documentato solo una volta e che altre parti della documentazione del codice possono collegarsi ad esso se vengono eseguite nell'applicazione.

Problemi :

Non riesco a navigare all'indietro dai collegamenti ipertestuali ( cioè non posso rispondere alla domanda: "Se cambio questo codice, quali casi d'uso sono interessati." Posso passare da Use-Case a Code, non il contrario. )
La parola documento si sente già goffo e disordinato dopo che ho appena iniziato a scrivere cose in esso.

Domanda : come posso documentare questa applicazione multilivello senza fare un gran casino?

documentation n-tier

posta Rafael Emshoff 20.03.2014 - 12:20

fonte

2 risposte

Leggi altre domande sui tag documentation n-tier

Prossimi passaggi per lo sviluppo di un nuovo prodotto [duplicato] Verifica che una funzione sia eseguita solo da __main__ in Python

score 1 · Answer 1

Un Wiki ben organizzato sarebbe il mio suggerimento. Ho usato Atlassian Confluence in passato. Credo che valga la pena dedicare del tempo, soprattutto dal punto di vista dell'azienda. Ci vuole un sacco di tempo e sforzi per creare, mantenere e applicare gli standard di documentazione, ma dopo che alcuni sviluppatori senior hanno lasciato un pasticcio di codice legacy, sarai contento di averlo fatto.

Un wiki può essere organizzato come una cartella di file e può anche creare pagine di indice per consentire all'utente di creare tutti i collegamenti necessari. Inoltre, la ricerca in Atlassian è eccellente.

Per gli utenti che non sono abbastanza esperti nel creare pagine, basta che creino documenti Word belli, quindi importali nel Wiki.

La cosa principale è avere una struttura ben definita e applicare gli standard di documentazione. Questo deve avere un buy-in completo dalla direzione al lavoro. Ho mantenuto un wiki per il mio gruppo precedente ed è diventato essenziale per le operazioni quotidiane perché l'ho tenuto pulito e organizzato.

score 0 · Answer 2

Nella mia esperienza, questo grande sforzo nella documentazione è una perdita di tempo. È meglio usare questa volta aggiungendo nuove funzionalità all'applicazione e apprezzando la tua attività o rielaborando le parti disordinate del codice, un documento word di solito non risolve alcun problema in un'applicazione software.

Non sto dicendo che documentare il suo non è necessario o è né una cosa buona, ma la documentazione di una tracciabilità (la capacità di passare dal codice alla cronologia degli utenti / caso d'uso) deve essere fatta giorno per giorno in un progetto non in un grande sforzo quando probabilmente è tardi.

Comunque, preferisco usare qualche strumento condiviso come una wiki, quando stai costruendo la prossima funzionalità per la tua applicazione scrivi la documentazione che pensi possa far risparmiare tempo al prossimo ragazzo e solo per quella parte dell'applicazione. In questo modo, aggiungi la preziosa documentazione passo dopo passo e il tuo (e tutto il team) apprende l'abitudine di rivedere la documentazione in ogni attività. Con grande sforzo di documentazione è molto comune che la documentazione finale sia di scarso valore e prima di quanto pensi sia completamente inutile e obsoleto perché il team non ha l'abitudine di modificare la documentazione con ogni nuova modifica nell'applicazione.

Per quanto riguarda la tracciabilità, utilizzare uno strumento di ticketing (come jira, trac, se si utilizza .net microsoft hanno buoni strumenti per questo) integrato con il tuo VCS e in ogni commit include il numero del ticket a cui si impegna. Ancora una volta è una pratica quotidiana che ti dà senza sforzo. Tracciabilità reale, tracciabilità in un wiki su un documento Word è solo un'illusione.