Ho completato un'applicazione web che è sostanzialmente sviluppata in PHP ed è solo un'altra normale applicazione web. Di solito, quando consegno la versione di produzione finale, consegno al client la documentazione del codice e le informazioni sull'architettura. Tuttavia, per questo particolare progetto il cliente insiste per avere i dati completi in e out sul progetto.

Quindi mi sto solo chiedendo ... Quali sono i documenti tecnici e non tecnici obbligatori che posso fornire al mio cliente oltre alle documentazioni sul codice e sull'architettura?

(Sarebbe anche piuttosto interessante colpire il cliente riguardo a varie statistiche e dati sul progetto in modo che conoscesse effettivamente la quantità di lavoro coinvolto e quanto sia bello il prodotto.)

Penso che l'elenco dovrebbe includere:

• I requisiti non tecnici (c'era un documento del genere, giusto?)
• I requisiti tecnici
• Un documento "decisionale" (se presente) che spiega perché alcune decisioni sono state prese rispetto ad altre. Questo potrebbe essere già in un documento di architettura o requisiti diversi, ma di solito lo facciamo separatamente per le decisioni importanti.
• Il codice e altre risorse (file di immagini, CSS, ecc ...)
• Il modello di database (come diagramma, documento, qualunque cosa)
• DDL per creare il database.
• DML per eseguire il seeding del database.
• Un documento che spiega la configurazione dell'applicazione e la risoluzione dei problemi di base.
• Un elenco di tutti i nomi utente e delle loro password importanti (per gli account Admin), nonché le istruzioni su come modificare la password. Idealmente, quando configurano il sito Web per la prima volta, dovrebbero essere invitati a inserire una nuova password amministratore, ma questa è più una questione di architettura.
• Requisiti di sistema e, per le app Web, anche requisiti minimi di hosting (L'app richiede MySQL o PostgreSQL? Quanta RAM ?, ecc ...)

Non tutte queste cose potrebbero essere disponibili (o necessarie) per ogni progetto, ma penso che questa sia una buona guida generale.

Oltre all'ottima risposta di FrustratedWithFormsDesigner, vorrei dire cosa includono i documenti non tecnici (come l'abbiamo fatto):

• i dati di analisi: cosa ti ha detto il cliente quando hai parlato per la prima volta dei requisiti?

• l'offerta che hai fatto:

  • il documento sui requisiti del prodotto
  • e il documento di specifica funzionale

  che insieme agiscono come una sorta di contratto su cosa devi fare e cosa ti aspetti che
  il cliente consegni durante lo sviluppo, nonché i tempi e i costi stimati.

• le specifiche, inclusi i protocolli di revisione, i casi d'uso e i piani di prova, i risultati dei test

• il design in UML e tutti i documenti corrispondenti

• la documentazione del codice sorgente (doxygen o altro)

• il manuale e le linee guida per l'installazione

• la quantità effettiva finale di risorse (tempo e denaro) utilizzate per il progetto, in modo da poter scrivere una fattura

• alcuni clienti desiderano anche i protocolli di riunione, che è quindi un'estensione del "documento decisionale" di cui sopra

Spero che sia quello che stavi cercando.

Segui la documentazione applicabile per il tuo progetto tra i seguenti: potresti già averne alcuni.

Documentazione tecnica:

• Dettagli su PHP e informazioni su come è utile per il progetto
• Dettagli sul back-end e informazioni su come è utile per il progetto
• Informazioni sulla connettività del database insieme a immagini appropriate che descrivono il flusso di dati
• Informazioni su altri linguaggi di programmazione o applicazioni coinvolti nel progetto come XML, HTML ecc.
• FAQ File di aiuto

Preparare i documenti con schermate ed evidenziare il codice pertinente (se necessario) per quanto segue:

• Informazioni sull'applicazione front-end come oggetti o controlli, proprietà degli oggetti ecc.
• Informazioni sulle query del database (se non sono già presenti)
• Informazioni sulle proprietà del database come chiave primaria, chiave esterna ecc. E su come garantiscono coerenza e accuratezza dei dati.
• Guida dettagliata in tutto il progetto usando schermate di tutti i possibili tipi di schermo usando sia il front-end che il back-end dopo averlo eseguito con i dati di esempio, senza ripetizione di simili tipi di dati o schermate, in un ordine logico.

• Inserisci dati non validi e mostra che è impossibile farlo poiché hai eseguito la convalida dei dati nel front-end e nel back-end.
  /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

• Mostrare che non vi sono errori nel programma o incoerenze nei dati se si verifica un errore improvviso nel sistema server o client spiegando il codice pertinente.

• Dopo aver fornito dati di esempio attraverso il front-end, è possibile includere query di esempio nel back-end per il recupero diretto dei dati dal server e includere anche query DML di esempio che possono aiutare a preparare statistiche vitali dei dati.

Dovresti verificarli tu stesso prima di documentarli in modo che se il tuo cliente richiede una demo con dati di esempio, puoi mostrare come funziona effettivamente il progetto. Inoltre, assicurati che il tuo codice front-end abbia delle righe di commento appropriate.

• Infine, concludi con le statistiche come il numero totale di righe di codice, il numero totale di giorni trascorsi verso il progetto, il numero totale di volte in cui hai controllato il progetto, un elenco di tutte le applicazioni utilizzate e altre informazioni tecniche e non tecniche.

  
  Documentazione non tecnica:

• Dettagli sulla licenza del progetto, se applicabile.
• Aspetti commerciali del progetto, se applicabile.

Diffidare

La documentazione potenziale che si potrebbe dare al cliente è praticamente infinita. Il tempo aggiuntivo necessario per generare la documentazione che non hai già non è pagato.

Perché il client desidera questa documentazione (oltre al codice sorgente)? Cosa ne verrà fatto? Per chi è?

Le risposte a queste domande aiuteranno a restringere la portata di cosa fornire.

È fondamentale che tu e il cliente concordiate esattamente quale documentazione consegnare e se qualsiasi ulteriore sforzo sarà compensato.

Non giocare a indovinare. La maggior parte della documentazione tecnica sarebbe inutile per il tipico client (non tecnico).

Probabilmente lo suddividerei in alcune categorie di documenti:

Guide:

• Guida all'installazione, come configurarlo su un server.
• Guida dell'amministratore, per come configurare ed eseguire l'applicazione per prestazioni ottimali. La sicurezza sarebbe anche qualcosa da coprire qui solo in modo che sia noto quali password ha questa applicazione e che usa per funzionare.

Supporto:

• Se ci sono problemi, che tipo di procedure suggeriresti? Stai fornendo supporto per un certo periodo di tempo? Probabilmente darei ancora una guida o due in quest'area, così qualcun altro conosce alcune delle cose più facili da provare come riavviare i servizi o riavviare un server.

Punti di integrazione:

• Esistono punti di integrazione di terze parti per questa applicazione che fanno affidamento su fornitori diversi dal codice?