Esistono prove formali che la documentazione in generale sia incompleta e obsoleta rispetto ad un certo grado? [chiuso]

-1

Sono uno sviluppatore web e attualmente mi trovo ancora una volta in una situazione in cui un reparto op in parte clueless richiede una documentazione "completa" necessaria per il supporto tecnico della nostra applicazione da parte di una terza parte, inclusa "ogni possibile situazione di errore" ". Dal momento che non esiste un terreno comune su ciò di cui questa terza parte dovrebbe essere capace (le ops parlano costantemente di "una persona della strada dovrebbe essere in grado di farlo"), ritengo che tale documentazione sia impossibile e la mia esperienza mi dice che ogni documentazione è obsoleto e incompleto, anche se solo un po '. Non posso fare a meno di chiedermi: c'è stato qualche studio o forse anche una prova che questo è effettivamente il caso? Forse persino i teoremi di incompletezza di Gödel potrebbero essere applicati qui?

    
posta Nikolai Prokoschenko 01.04.2014 - 14:42
fonte

3 risposte

5

Non conosco alcuna prova formale, ma ecco alcuni suggerimenti per risolvere il tuo vero problema. Stai pensando a questo troppo come un programmatore. Non prendere letteralmente "ogni possibile situazione di errore", quando tutti sappiamo che non è possibile documentare cose di cui non si è a conoscenza. Nella tua mente sembra che stiano richiedendo un documento perfetto. Sia che ci sia una prova definitiva o meno, hai già concluso che è impossibile in questa situazione.

Qualcuno deve avere una discussione su ciò che realmente chiedono e su cosa è in grado di creare e arrivare ad un accordo.

Anche se un codice base non cambia, ci sono applicazioni in cui gli utenti adattano le funzionalità facendo cose che i progettisti non hanno mai immaginato. Sarà difficile per un sacco di personale di supporto pensare a diversi modi in cui l'app può essere utilizzata e come supportarla. Esempio: ho lavorato come responsabile del supporto per una società di software per la fatturazione dell'acqua e un cliente ha chiesto a uno dei nostri dipendenti del personale di supporto iniziale se potevano fatturare la spazzatura. Era un prezzo forfettario e la nostra app aveva la possibilità di personalizzare l'etichetta su ogni tariffa. Nella mia mente era ovvio, chiamarlo flat-fee come vuoi.

La tua documentazione potrebbe dover adattare un approccio un po 'agile per tenerlo aggiornato. Forse questo potrebbe essere sotto forma di wiki o qualche altro tipo di sito web che puoi mantenere e aggiornare frequentemente. Certo, vogliono che tutto sia scritto in anticipo e perfetto, ma non succederà. Dovrai apportare correzioni e aggiunte e questa sarà una tassa continua che stanno cercando di evitare. Chiedi al cliente con quale frequenza sono in grado di leggere le istruzioni per qualsiasi cosa e di comprenderlo appieno? Il software è molto più complicato rispetto alla creazione di una libreria.

    
risposta data 01.04.2014 - 15:23
fonte
0

Potresti argomentare che veramente completa documentazione - documentazione che descrive esattamente cosa fa il software con ogni file system, rete e input dell'interfaccia utente e output e ogni condizione di errore e maiuscole / minuscole - è dettagliato come il codice sorgente ed è effettivamente indistinguibile dal codice sorgente. Dopotutto, il codice sorgente non è altro che una descrizione leggibile da una macchina di come il software dovrebbe prendere tutte queste decisioni.

Dubito che i tuoi clienti vogliano il codice sorgente o che voglia pagare per duplicare il codice sorgente. Per i punti bonus, considera che gran parte del comportamento della tua applicazione dipende dal suo sistema operativo, dalle sue librerie e dai suoi framework e che la documentazione completa coprirebbe quindi anche quelli.

Come @JeffO e @ DocBrown ha detto, tuttavia, l'adozione di questo approccio è probabilmente l'applicazione di un pensiero programmatore eccessivamente letterale a una domanda di relazioni con gli utenti, e l'approccio migliore è cercare di scoprire e affrontare le loro preoccupazioni di fondo. / p>     

risposta data 01.04.2014 - 21:15
fonte
0

La produzione di tale documentazione è teoricamente possibile se:

  • Il software rimane statico (o tutte le modifiche sono immediatamente documentate)

  • Tutte le possibili eccezioni vengono catturate e registrate con la loro esatta posizione nel codice

  • Le suddette eccezioni sono state catturate in natura e producono l'output previsto definito nella documentazione

Perdona la mia crudezza, ma hai tutte le probabilità che tutto questo sia vero come un uomo con una gamba sola che vince un concorso di calci in culo.

Il codice è raramente (se mai) perfetto, la documentazione è doppiamente così.

Sembra che il tuo reparto operativo stia cercando di assolvere da qualsiasi responsabilità se qualcosa va storto. Gli errori accadono nonostante i migliori risultati ed è fantastico cercare di convincere te stesso altrimenti.

    
risposta data 01.04.2014 - 16:19
fonte

Leggi altre domande sui tag