È probabile che il tuo fornitore produca il minimo richiesto per adattare la tua definizione di documentazione .
Dovrai passare un po 'di tempo a pensare a quale tipo di documentazione vuoi, e possibilmente fornirgli dei template, una wiki, ecc. che vuoi che usino se non vuoi diventare spazzatura quando hai finito e vuoi che sia facile aggiornarlo man mano che le cose cambiano.
Di cosa hai probabilmente bisogno? Penso a documenti accessibili a diversi tipi di persone, a diversi tipi di livelli decisionali. Come ha detto il maniaco del cricchetto, c'è un sacco di spazzatura generata automaticamente che aggiunge valore zero e raramente ottieni una buona informazione a un livello molto dettagliato. Inoltre, gli sviluppatori di software sono generalmente buoni con i dettagli. Hai bisogno di una buona documentazione per comunicare con le parti interessate e la gestione.
Penso che vorrai cose che spieghino a diversi livelli di dettaglio. Usando l'analogia dell'altitudine dell'aereo, un esempio (varia le altitudini per la tua organizzazione. Dal momento che dici che il tuo software commissionato sarà utilizzato da diverse aziende, potresti aver bisogno di più livelli):
-
La vista 30.000 m per i responsabili delle decisioni ad un livello molto alto, per quando sono necessari grandi cambiamenti. (Ad esempio, come questo software si integra con i sistemi, le interfacce e le componenti principali esistenti) Potresti aver bisogno di più di uno di questi, se hai disparati sistemi esistenti, così la negoziazione può essere fatta tra le diverse compagnie di cui parli. Soprattutto, questo deve essere breve e chiaro, con diagrammi e in linguaggio naturale che una persona NON-TECNICA può capire.
-
La visualizzazione 15.000 m per i team di progetto che potrebbero essere incaricati dai responsabili delle decisioni. Vorrà che questo includa le differenze specifiche nel software per le diverse società che discuti in alto. Ci sono SEMPRE situazioni uniche per ottenere da un progetto teorico per far funzionare le cose. A seconda del luogo in cui viene effettuato il materiale one-off (da singole aziende o da questo gruppo di sviluppo), ciò potrebbe risultare complicato. Ancora, brevità, linguaggio non tecnico e diagrammi sono più utili . Non dovrebbe importare in quale lingua è scritto il codice, ecc. Affinché le persone capiscano questa documentazione. Lo vuoi come strumento di negoziazione con le compagnie utenti e con il team di sviluppo.
-
La 5.000 m vista dei principali componenti del codice e il loro adattamento. Ecco il primo posto in cui il linguaggio tecnico può iniziare a essere utile. Questo è per i team di progetto che devono specificare i cambiamenti e determinare quali grossi pezzi di lavoro devono essere fatti. Qui è dove gli sviluppatori, i progettisti e iniziare il back and forth di come le cose verranno fatte, quali parti del software dovranno essere cambiate, ecc.
Questo è quello che vorrei. Sono uno sviluppatore / integratore in una grande organizzazione multi-sito. Sono spesso in teleconferenza con persone non tecniche che non si preoccupano dei dettagli e stanno cercando di capire il gergo della gente IT che ama i dettagli. Hai bisogno di documenti che comunichino lo spazio tra le immagini grandi ei dettagli, in modo che tu possa mettere tutti nello stesso posto durante le discussioni.