Cosa comprende esattamente la "documentazione"?

Quando diciamo "documentazione" per un prodotto software, cosa include e cosa non dovrebbe includere?

Ad esempio, una domanda recente ha chiesto se i commenti sono considerati documentazione?

Ma ci sono molte altre aree per cui questa è una domanda valida, alcune più ovvie di altre:

• Manuali (ovviamente)
• Note di rilascio?
• Esercitazioni
• Commenti
• Chiunque altro?

Dov'è tracciata la linea. Ad esempio, se "tutorial" è documentazione, è documentazione di "video tutorial" o è qualcos'altro?

Generalmente, qualcosa nel software non viene "fatto" fino a quando non viene implementato, testato e documentato. Da qui questa domanda, quali cose dovremmo considerare come parte della documentazione per considerare qualcosa di "fatto".

_{La domanda si ispira al recente feedback dei clienti durante la nostra conferenza indicando che il nostro documento aveva bisogno di più "campioni", che in precedenza non eravamo stati bravi a considerare come avremmo dovuto essere.}

_{Pubblico: sviluppatori di software che utilizzano i nostri database, i linguaggi di programmazione e gli strumenti associati (come i client di amministrazione di detto DB)}

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 esempio un corso di formazione di una settimana non è documentazione ma i materiali del corso lo sono; una chat di cinque minuti sulla lavagna non è documentazione ma un'immagine della lavagna lo è.

Tenendo presente l'obiettivo (spiegando il software), la documentazione è terminata quando il cliente è soddisfatto della spiegazione : proprio come il software è finito quando il cliente è soddisfatto del software. Tieni presente che il cliente per la documentazione non è sempre uguale al cliente che paga per il software: il personale di supporto, i tester, i venditori e altri dovranno tutti capire cosa fa il software e come funziona.

Questo aiuta a capire dove si trova il limite per ciò che dovrebbe essere incluso nella documentazione. Usando "reader" come una comoda scorciatoia, anche se accettiamo che possano essere inclusi video o audio: tutto ciò che aiuta il lettore a ottenere le informazioni di cui ha bisogno sul software è la documentazione che può usare, tutto il resto no. Se il cliente ha bisogno di istruzioni dettagliate su tutti i casi d'uso, è necessario che questo faccia parte della documentazione. I tuoi sviluppatori probabilmente hanno bisogno del codice sorgente, delle informazioni sul repository di controllo della versione e delle istruzioni di costruzione: questa è la documentazione per loro, ma come descritto sopra non farebbe parte della documentazione del cliente.

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

Il problema che hai riscontrato è che hai avuto una disconnessione tra ciò che pensavi fosse necessario per il cliente e ciò che si aspettavano che consegnassi, così alla fine hai avuto la sorpresa "ehi 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 quanta documentazione ha bisogno il tuo progetto. Ogni progetto è diverso e spetta al tuo team, al proprietario del prodotto e ai tuoi clienti determinare il livello e il tipo di documentazione richiesta per il tuo progetto.

Alcuni fattori che entrerebbero in gioco:

• Stai sviluppando il software v1.0 e questi stanno passando ad altri progetti o è in corso un progetto a lungo termine? Commenti / documenti di progettazione diventano molto più importanti in quest'ultimo caso. D'altra parte, se il tuo cliente è un negozio di ciambelle mamma-e-pop e stai scrivendo un sito Web per loro che non vedrai mai ... beh, immagino che la documentazione del codice sia carina 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 utenti finali tipici o sono altri sviluppatori? Hai un'API / SDK che stai esponendo?
• Qual è il livello di competenza dei tuoi clienti? Ciò influisce sulla scelta del tutorial video rispetto al materiale scritto rispetto a una sorta di app tutorial interattivo
• I tuoi clienti si preoccupano di ciò che è cambiato da versione a versione. Alcuni lo fanno. La maggior parte no. Per pochi è la legge (o vicino a quella) a preoccuparsene.

La documentazione è roba destinata a essere letta senza modificarla.

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

• ^{Definire correttamente lo scopo della documentazione non è del tutto semplice. La distinzione semplice (ingenua se lo si desidera) che viene in mente naturalmente è che la documentazione è tutto ciò che è destinato alla lettura - mentre, per confronto, il codice è qualcosa destinato all'esecuzione al computer . Sembra carino in superficie vero? ma risulta davvero brutto una volta che scavi più a fondo.
   
  Il fatto è che un buon codice tiene conto dei problemi di leggibilità, insieme alla correttezza dell'esecuzione - questo rende la distinzione della "leggibilità" piuttosto inutile nella definizione della documentazione.
   
  Gli stessi esempi che hai citato mostrano che cosa c'è che non va. I clienti in genere si aspettano che questi siano scritti in modo chiaro eeseguire correttamente. Compromettere la leggibilità o la correttezza può portare a una cascata di reclami dei clienti. La distinzione ingenua non aiuta a capire se i campioni sono codice o documentazione.
   
  L'uso della distinzione ingenua diventerà ancora più complicato se immagini di lavorare con l' open source . Lo scarichi, lo crei e lo esegui - non lo leggi, è solo il codice giusto? Aspetta, le cose in qualche modo sono andate male e arrivi al codice per leggere cosa sta succedendo lì ... hey hai letto non eseguito - questa documentazione è adesso? E, infine, trovi il bug nel sorgente e lo risolvi - ora questo è davvero il codice, non è qualcosa che normalmente viene chiamato documentazione, non importa quanto attentamente lo leggi per fare quella correzione.}

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

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

Ora, se c'è un problema con il campione o l'ambiente modificato, non è più colpa tua - intendo nessun bug nella documentazione, poiché i documenti non sono destinati alla modifica. Qualunque aiuto forniate agli utenti in questo caso, rientrerebbe nella categoria di supporto, non in una correzione di bug.

Tutto ciò che risponde a una domanda "come posso ..." è la 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 il mio progetto risponde a tutti i miei requisiti"), piani di test ( "come faccio a sapere le mie opere codice"), unit test ( "come faccio a sapere che ho safisfied requisito X"), commenti in linea ( "come faccio a rendere sicuro che la prossima poveri schlub capisce perché l'ho scritto questo modo "), istruzioni di distribuzione (" come impacchettare questo prodotto per l'installazione "), ecc.

Per gli utenti, ciò significa manuali per l'utente ("come si usa il software"), tutorial ("come si usa questa funzione specifica"), note di rilascio ("come faccio a sapere quali bug sono stati corretti / nuove funzionalità di bug sono state aggiunto "), ecc.