Come documentare un piccolo sito web esistente (applicazione web), dentro e fuori?

Question

Abbiamo una "applicazione web" che è stata sviluppata negli ultimi 7 mesi. Il problema è che non era veramente documentato. I requisiti consistevano in un piccolo elenco puntato della riunione iniziale di 7 mesi fa (è più una dichiarazione "obiettivi" che i requisiti software). Ha raccolto una serie di caratteristiche che derivano da piccole discussioni verbali o di chat.

Lo sviluppatore è in partenza molto presto. Ha scritto lui stesso l'intera faccenda e conosce tutte le stranezze e le regole sottostanti per ogni pagina, ma nessun altro sa davvero molto di più del lato dell'interfaccia utente; che ovviamente è la parte facile, poiché è fatta per essere intuitiva per l'utente. Ma se qualcuno ha bisogno di riparare o aggiungere una funzionalità ad esso, l'intera cosa è una scatola nera. Il codice ha alcuni commenti minimi e, naturalmente, la cosa buona delle applicazioni web è che la barra degli indirizzi punta nella giusta direzione verso la risoluzione di un problema o l'aggiornamento di una pagina.

Ma come lo sviluppatore dovrebbe documentare questa applicazione web? È un po 'perso fino a dove cominciare. Come sviluppatori, come si documentano completamente le applicazioni Web per altri sviluppatori, manutentori e utenti a livello amministrativo? Quale approccio usi, da dove parti, quale software usi, hai un modello?

Un'idea di grandezza: utilizza PHP, MySQL e jQuery. Ha circa 20-30 file principali (frontend), insieme a circa 15 file inclusi e un paio di cartelle di alcune risorse - quindi nel complesso è un'applicazione piuttosto piccola. Si interfaccia con 7 tabelle MySQL, ognuna con un buon nome, quindi penso che la fine del database sia piuttosto auto-esplicativa. C'è un file config.inc.php con le definizioni di conss come i dettagli utente di MySQL, alcuni da/verso e-mail e URL che PHP usa per inserire in e-mail e pagine (percorsi relativi e assoluti, in modo base). C'è qualche AJAX tramite jQuery.

Si prega di commento, se c'è qualche altra informazione che mi avrebbe aiutato aiuto e sarò lieto di modificarla in.

---

Lo sviluppatore lascia il Venerdì. Tuttavia, può dedicare la maggior parte delle sue 24 ore rimanenti a questo compito di documentazione. Quindi, sì, le cose sono desolate ma 24 ore sono un po '... giusto? : - \

Answer 1

Vorrei iniziare elencando le funzionalità principali attualmente implementate dall'applicazione (aggiornare i punti elenco iniziali).

Quindi, per ciascun punto elenco, annotare i requisiti principali associati a tale punto.

Per ciascun requisito, scrivere:

• Tutto eccentrico su quel particolare requisito
• Dove nel codice tale obbligo è implementato (che php, file inc, tabelle)

Questo ti darà qualcosa di una gerarchia di tracciabilità

Feature => Requisito => Implementazione

Fornirà inoltre un buon framework per spingere i ricordi e scrivere i getcha.

Quindi, commentare ciascuna pagina php e inc.

Inizia con un'intestazione che delinea lo scopo e quali requisiti del precedente elenco sono soddisfatti (rintracciabilità da codice a requisito).

Passare attraverso ogni file php/inc e commentare le principali azioni/decisioni/cicli che indicano ciò che stanno cercando di realizzare e tutte le considerazioni progettuali che sono assunte (ad esempio "si presume che l'input sia stato convalidato nel passaggio precedente") .

Quando si commenta il codice sorgente, è possibile utilizzare uno strumento come PHPDoc in modo che sia possibile generare documentazione dai commenti.

Answer 2

Un approccio potrebbe essere quello di organizzare una serie di riunioni di consegna. In questi lo sviluppatore dovrebbe spiegare il codice per ogni sezione.

Poteva scrivere alcune note in preparazione per queste, ma far sì che anche gli altri sviluppatori prendessero minuti potrebbe aiutarli a capire il codice. Anche questi incontri sarebbero l'occasione per porre domande su aspetti non chiari.

Non provare a fare tutto il sito in una volta. Scomposizione in due blocchi più piccoli raggruppati in qualche modo: per funzione o per area. Ciò significa che gli altri sviluppatori non sono bombardati da troppe informazioni in una volta sola, lo sviluppatore originale può concentrarsi su un'area alla volta e avere la possibilità di seguire l'incontro.

Anche se nulla "si attacca" subito, ci sarà una certa familiarità con il sito quando lo si rivisiterà più tardi.

Un altro approccio potrebbe essere per lo sviluppatore dare una serie di brevi presentazioni sul sito e come è stato costruito. Questo potrebbe indurlo a ricordare perché ha preso gli approcci che ha fatto. Questo è inestimabile quando si guarda al codice. Se sai che problema cercavi di risolvere è molto più facile da capire.