Il titolo dice tutto davvero.
A volte può finire per affermare che lo sviluppo e l'IT sono a rischio per questo genere di cose. Quale livello di documentazione ti aspetti quando dovresti installare, applicare patch, mantenere, avviare, arrestare e diagnosticare una soluzione in esecuzione su uno o più server?
Risposte:
Tutte queste cose dovrebbero essere documentate in dettaglio, anche se quando l'operazione è standard per il sistema operativo, il server delle applicazioni, il web server ecc., Si potrebbe essere in grado di assumere le operazioni IT che le persone sanno come fare.
Installazione: documenta tutto su come è installato e configurato, incluso come sapere se funziona correttamente.
Parlaci dell'architettura, in particolare della comunicazione tra i vari componenti della soluzione (ad es. Intervallo di porte - i meccanici RPC utilizzano spesso un intervallo di porte - dobbiamo sapere qual è l'intervallo e quando l'applicazione potrebbe esaurire le porte).
Patching: documenta tutto ciò che è specifico dell'applicazione: cosa deve essere chiuso prima del patching e qualsiasi azione di follow-up dopo il patching (cache, indici, proxy che potrebbero dover essere cancellati o ricostruiti).
Manutenzione: documentare l'aspetto dell'operazione normale e anormale - quali code e altre cose devono essere monitorate e qual è la gamma normale di queste.
Dicci come gestire i dati, in particolare tabelle e file che crescono senza limiti (ad es. File di registro e cronologie delle transazioni). Come devono essere eliminati e qual è l'impatto della rimozione di voci precedenti? (su segnalazione ecc.).
Spiegaci come eseguire le normali azioni "gestionali come al solito" / di gestione della vita - ad esempio, ad esempio, si potrebbe aggiungere o modificare account utente.
Parlaci di qualsiasi altra azione di gestione regolare che potrebbe essere richiesta (ad es. Quali certificati vengono utilizzati e cosa fare quando scadono).
Per tutte le modifiche, spiegaci come ripristinarle (non tutte le modifiche hanno esito positivo). E dicci che hai testato i piani di rollback!
Diagnosi: formati e percorsi dei file di registro dei documenti e OGNI messaggio di errore dell'applicazione che potrebbe apparire, indicando che cosa significa che il messaggio di errore è andato storto e che potrebbe essere necessario modificare per risolverlo. Non utilizzare mai lo stesso messaggio di errore per due eventi diversi.
Abbattimento e avvio: come, quale ordine, eventuali procedure speciali (ad esempio, consentire ai server di svuotare le connessioni prima di spegnerle).
Non sono assolutamente d'accordo sul fatto che il modo migliore per farlo sia gettare l'applicazione oltre la recinzione e lasciare che il personale IT risolva ciò che è necessario. La documentazione operativa (e in generale, le caratteristiche di gestibilità dell'applicazione) deve essere pensata in anticipo.
Una domanda successiva sarebbe: cosa succede quando (non se) gli sviluppatori non forniscono una documentazione sufficiente?
Raccomando che l'IT abbia la possibilità di inserire rapporti sui difetti rispetto al software, utilizzando qualsiasi sistema di tracciamento dei difetti utilizzato dagli sviluppatori. In questo modo, se non ti dicessero, ad esempio, che i file in una determinata cartella devono essere eliminati e che debba essere conservato solo il valore di una settimana, potresti inserire un difetto che dice "l'applicazione riempie il disco con i file di registro "e suggeriscono di lavorare con l'IT su una tecnica documentata per eliminare quella cartella.
Il mio elenco di requisiti per la documentazione sarebbe (non in alcun ordine specifico):
(documentazione su :)
Documentazione come questa sono esempi di buona documentazione:
Considererei la documentazione come questa piena di fallimenti:
Anche il manuale di FreeBSD è un ottimo esempio di documentazione e l'approccio di OpenBSD. Hanno buttato fuori cose che non sono adeguatamente documentate.
EDIT: questo elenco non è affatto completo, è solo la roba di base che mi è venuta immediatamente in mente. Anche la documentazione dovrebbe essere ben leggibile, non solo qualcosa che si legge come qualcuno vomitato .
In breve, mi aspetto la documentazione per la quale specifico e contratto.
Troppe volte questo dettaglio critico è escluso da un accordo. L'utente finale se lo aspetta e lo desidera gratuitamente. I buoni sviluppatori correggeranno questa supervisione nelle prime fasi del processo e fisseranno le aspettative, incluso un requisito di prezzo e tempo.
Credo che l'IT debba comunicare con gli sviluppatori quale tipo di documentazione è necessaria. Il modo migliore per farlo è se lo sviluppo fornisce versioni pre-release (o versioni di iterazione) di una soluzione con cui l'IT può giocare e testare in modo che l'IT possa rispondere con ciò che è necessario.
La creazione di note di rilascio adeguate con un'applicazione sarebbe un buon inizio. In caso di modifiche al comportamento corrente con il rilascio, eventuali note dal QA sulle modifiche alle dipendenze o sui comportamenti di avvio / arresto, modifiche nel carico su server o database dipendenti, ecc.
@Spoike (non posso ancora commentare le risposte ..)
Gli implementatori IT (il ruolo varierà in base al tipo e alle dimensioni dell'azienda) devono lavorare in modo coerente per ottenere quanto segue:
Requisiti minimi di installazione / turnover - in altre parole, l'IT non può essere passivo e si aspettano che gli sviluppatori "sappiano" quali informazioni sono necessarie al momento dell'installazione / turnover. Ho scoperto che c'è spesso una notevole confusione / disaccordo nell'IT su ciò che costituisce la corretta documentazione di un'app. Dev comprende i requisiti (speriamo) e l'IT deve essere caucus per trovare ciò che è necessario.
Una procedura di installazione / turnover : nelle impostazioni aziendali è possibile chiamare questo controllo delle modifiche o governance, ma si tratta essenzialmente di un ciclo di revisione standard in cui l'IT si affianca a Dev PRIOR top install per ottenere un briefing sul prodotto e le sue esigenze.
L'installazione di un'app non è diversa dal debutto di una produzione teatrale. Prima che si alzi il sipario, il regista (capo sviluppatore) si incontra ripetutamente con il team di produzione scenica (implementatori IT) per assicurarsi che tutto sia "così" per la serata di apertura (installazione pubblica).
Non puoi cambiare la persona Dev (perché dovresti farlo?), Ma puoi indicare il tuo obiettivo condiviso di un'app fantastica che funziona incredibilmente veloce per tutti gli utenti. I requisiti del documento IT di consenso sono solo una delle cose necessarie per garantire ciò.