Il team di sviluppo ha terminato un sito Web e il mio compito è preparare un documento in modo che altri programmatori possano mantenere il sito web con facilità.
Non ho esperienza in questo e vorrei chiedere che cosa dovrebbe essere menzionato (struttura del documento) in quel rapporto?
Finora la mia idea è solo quella di preparare un diagarm ERD per il database e il diagramma di flusso per ogni funzione. Qualsiasi altro suggerimento, ad es. quali sono i cookie memorizzati?
Per un sito web commerciale su piccola scala, è una buona idea avere:
Documentazione relativa al database .
Non dimenticare il file SQL che crea il database. La documentazione dovrebbe anche descrivere l'infrastruttura stessa (ad esempio quanto sono frequenti i backup, ecc.)
Documentazione tecnica (non il manuale dell'utente, ma la documentazione che descrive cose come l'architettura dell'applicazione).
Se il costo è proibitivo, la documentazione tecnica potrebbe mancare se il codice è abbastanza chiaro. Se, d'altra parte, il codice non è stato refactored per mesi, è una buona idea scrivere almeno una breve descrizione dell'architettura.
Opere originali .
È bello avere immagini JPG e PNG effettivamente utilizzate sul sito Web, ma quando la richiesta consiste nel modificare un'immagine, è quasi impossibile (o almeno molto costosa) senza il file Photoshop originale.
Lo stesso vale per qualsiasi altra cosa. Come freelancer, mi è stato chiesto due volte di modificare un sito Web ASP.NET senza codice sorgente originale. Ogni volta, il cliente è stato sorpreso di apprendere che non è possibile a un costo ragionevole.
Lavorare con JavaScript minisito (senza fonte originale) non è neanche divertente.
Documentazione sui processi , in particolare sul processo di distribuzione.
Ad esempio, come è stato minimizzato il file JavaScript? Quale strumento viene utilizzato per combinare i file CSS in uno? Quale versione di ASP.NET MVC devo installare sul server?
Informazioni legali (licenze, fonte originale, ecc.).
Di solito è un incubo quando si vuole determinare cosa è coperto da quale licenza. Ho il diritto di riutilizzare un contenuto? Dove trovo l'autore originale? Chi ha scritto una parte di testo su una pagina specifica del sito web?
Inoltre, quali sono le leggi particolari che si applicano al sito web? Ci sono delle azioni legali? Che dire delle cose obbligatorie come la scelta dei cookie di tracciamento nell'UE?
Informazioni di contatto .
Chi devo contattare se ho un problema con la grafica (ad esempio manca il file Photoshop originale per una parte del sito Web)? Chi è legalmente responsabile del sito web? ecc.
roba relativa alla sicurezza .
Proprio oggi, ho ricevuto una e-mail da un mio cliente, chiedendo se posso ripristinare la password di root persa del server, dato che l'account di root è stato creato dal provider di hosting, e non l'ho mai usato ( e mai dovrebbe usare) questo account me stesso.
Quando nulla è documentato, non è raro che tutti utilizzino lo stesso account (root) per connettersi al server. Per evitare situazioni così critiche, la documentazione deve descrivere le politiche relative agli account (chi può crearli, per chi e in quali casi, notare che non si dovrebbe mai includere alcuna password nella documentazione), le informazioni sui dati critici per la sicurezza, ecc.
Piano di ripristino di emergenza .
Se un giorno il tuo provider di hosting ti contatta per dire che tutti i tuoi dati sono stati distrutti dopo che il tuo sito Web è stato violato o dopo che il data center è stato inondato, avere un piano di disaster recovery è dolce. Assicurati che sia stato testato e che sia costantemente aggiornato.
Molte app web non ne hanno, quindi anche se potrebbero avere alcuni backup, di solito non sono in grado di ripristinarsi dopo un grave disastro o di impiegare settimane a recuperare, poiché nessuno conosce la configurazione precisa.
Punti aggiuntivi per il controllo della versione (con la cronologia delle revisioni) e il sistema di tracciamento dei bug (con tutte le segnalazioni di bug).
Questi sono i must per qualsiasi sito web commerciale. Se stai lavorando su un progetto di grandi dimensioni che richiede più affidabilità di un normale sito web, Stack Exchange non ti aiuterà: ci sono molti documenti da avere, ognuno dei quali viene scritto usando standard, processi, ecc. Specifici, e il il soggetto è troppo ampio per rientrare in una risposta.
Si noti che in pratica le app web non hanno alcuna documentazione. Quando i clienti mi chiedono di modificare i loro siti web, praticamente in ogni caso le uniche cose che ho avuto sono state il codice spaghetti e una breve descrizione a metà pagina scritta male del progetto.
Il caso migliore che ho avuto era un'app Web per una delle più grandi aziende francesi: non solo avevo alcuni requisiti (scritti da una persona che non ha mai imparato a scriverli), ma Ho anche avuto l'SQL per creare la struttura del database e l'accesso a SVN.
Leggi altre domande sui tag web-development maintenance documentation