Che cosa comprende esattamente "Documentazione"?

L'obiettivo della documentazione è descrivere e spiegare il prodotto software, in modo da poter definire la documentazione come l'insieme di artefatti che contribuiscono a tale descrizione o spiegazione. Probabilmente non considereresti le azioni correlate come parte della documentazione: ad es. un corso di formazione di una settimana non è documentazione ma i materiali del corso sono; una chat di cinque minuti per la lavagna non è documentazione ma un'immagine della lavagna è.

Tenendo presente l'obiettivo (spiegando il software), la documentazione è completa quando il cliente è soddisfatto della spiegazione : così come il software è finito quando il cliente è soddisfatto del software. Tieni presente che il cliente per la documentazione non è sempre lo stesso del cliente che paga il software: personale di supporto, tester, addetti alle vendite e altri avranno bisogno di una certa comprensione di ciò che fa il software e di come funziona.

Questo aiuta a capire dove si trova il tuo limite per ciò che dovrebbe essere incluso nella documentazione. Usando il "lettore" come una comoda abbreviazione, accettiamo anche che possano essere inclusi video o audio: tutto ciò che aiuta il lettore a ottenere le informazioni di cui hanno bisogno sul software è la documentazione che possono utilizzare, tutto il resto non lo è. Se il cliente ha bisogno di dettagliate spiegazioni di tutti i casi d'uso, allora deve essere parte della documentazione. I tuoi sviluppatori probabilmente necessitano di codice sorgente, informazioni sul tuo repository di controllo versioni e istruzioni di compilazione: questa è la documentazione per loro, ma come descritto sopra non farebbe parte della documentazione del cliente.

Penso che hai tolto la parte sbagliata dalla tua conversazione a una conferenza. Le moderne metodologie di sviluppo del software sostengono che il team di sviluppo dovrebbe lavorare a stretto contatto con i suoi clienti (o il proprietario di un prodotto che agisce come un proxy del cliente). Per tutto il lavoro svolto, la definizione di "fatto" è qualcosa che viene negoziata tra il team e il suo cliente e viene eseguita su base ricorrente mentre il software è in fase di sviluppo.

Il problema in cui ti sei imbattuto è che hai avuto una disconnessione tra quello che ritenevi necessario al cliente e quello che si aspettavano che tu consegnassi così alla fine hai ottenuto la sorpresa "hey dove sono tutti i campioni".

Per quanto riguarda la documentazione ... beh, è praticamente tutto ciò che hai elencato e forse poche altre cose che non hai fatto. Ma nessuno può dirti di quanta documentazione ha bisogno il tuo progetto. Ogni progetto è diverso e spetta al tuo team, al proprietario del tuo prodotto e ai tuoi clienti determinare il livello e il tipo di documentazione richiesti per il tuo progetto.

Alcuni fattori che entrerebbero in gioco:

• Stai sviluppando il software v1.0 e loro stanno passando ad altri progetti o questo è un progetto a lungo termine? I commenti / i documenti di progettazione diventano molto più importanti in quest'ultimo caso. D'altra parte se il tuo cliente è un negozio di ciambelle mamme e papà e stai scrivendo un sito web per loro che non vedrai mai ... beh, immagino che la documentazione del codice sia bella ma non così importante.
• Stai sviluppando un gioco per dispositivi mobili o un software che controlla il cardiofrequenzimetro in un ospedale. Indovina quale avrà la definizione di "fatto" che ha molta più documentazione?
• I tuoi clienti sono tipici utenti finali o sono altri sviluppatori? Hai un API / SDK che stai esponendo?
• Qual è il livello di esperienza dei tuoi clienti? Ciò influisce sulla scelta del video tutorial rispetto al materiale scritto rispetto ad un qualche tipo di app per tutorial interattivi
• I tuoi clienti si preoccupano di cosa è cambiato da versione a versione. Alcuni lo fanno. La maggior parte non lo fa. Per pochi è la legge (o vicino a questo) a cui badare.

La documentazione è roba da leggere senza modificarla.

Penso che non si possa sbagliare con la definizione basata sugli scopi ... ma solo se si definisce lo scopo in modo appropriato.

• <sup>Definire correttamente lo scopo della documentazione non è abbastanza semplice. La distinzione semplice (ingenua se lo si desidera) che viene in mente naturalmente è che la documentazione è tutto ciò che è inteso per la lettura - mentre, per confronto, il codice è qualsiasi cosa destinata all'esecuzione del computer . Sembra bello in superficie, no? ma risulta davvero brutto una volta scavato più a fondo.
  
  Il fatto è che il buon codice tiene conto dei problemi di leggibilità, insieme alla correttezza dell'esecuzione - questo rende la distinzione di "leggibilità" piuttosto inutile nella definizione della documentazione.
  
  Gli stessi campioni che hai citato mostrano cosa c'è di sbagliato in questo. In genere i client si aspettano che questi siano scritti in modo chiaro e eseguiti correttamente. Compromettere la leggibilità o la correttezza può portare a una cascata dei reclami dei clienti. La distinzione ingenita non aiuta a capire se i campioni sono codice o documentazione.
  
  L'uso della distinzione naïf diventerà ancora più complicato se immagini di lavorare con open source . Scaricalo, costruisci ed eseguilo - non lo leggi, è solo il codice giusto? Aspetta, le cose in qualche modo sono andate storte e si arriva al codice per leggere cosa sta succedendo lì ... ehi tu leggi non eseguire - questa documentazione è adesso? E, infine, trovi il bug nel sorgente e lo aggiusti: ora questo è veramente il codice, non è qualcosa che normalmente si chiama documentazione, non importa quanto attentamente lo leggi per fare quella correzione.</sup>

Per gli "campioni" che fornirai, la distinzione in lettura e non modifica potrebbe risultare piuttosto importante.

Guarda, se un campione fallisce quando viene eseguito invariato, nell'ambiente di riferimento documentato, è il tuo bug - bug nella documentazione, che devi accettare e correggere, bene.

Ora, se c'è un problema con il campione o l'ambiente modificato, non è più colpa tua - voglio dire nessun bug nella documentazione, dal momento che i documenti non sono intesi per la modifica. Qualsiasi aiuto tu fornisca agli utenti in questo caso, rientrerebbe nella categoria di supporto, non come una correzione di bug.

Qualunque cosa che risponda a una domanda "come faccio a ..." è documentazione.

Per gli sviluppatori, ciò significa specifiche dei requisiti ("come faccio a sapere cosa scrivere"), documenti di progettazione ("come posso soddisfare i miei requisiti"), matrici di tracciabilità ("come faccio a sapere che i miei indirizzi progettati tutti i miei requisiti "), piani di test (" come faccio a sapere che il mio codice funziona "), test di unità (" come faccio a sapere che ho soddisfatto il requisito X "), commenti in linea (" come posso essere sicuro il prossimo povero schlub capisce perché l'ho scritto questo modo "), le istruzioni di distribuzione (" come faccio a pacchettizzare questo prodotto per l'installazione "), ecc.

Per gli utenti, che significa manuali utente ("come utilizzo il software"), tutorial ("come utilizzo questa funzione specifica"), note di rilascio ("come faccio a sapere quali errori sono stati corretti / nuovi < sono state aggiunte funzionalità di strike> bugs "), ecc.