Quando scrivo il mio, mi sono sempre dedicato a scrivere due tre set. L'elenco di controllo per iniziare, con un'appendice MOLTO PIÙ LUNGA sull'architettura del sistema, incluso il motivo per cui le cose vengono fatte così come sono, i probabili punti critici quando si va online e le ipotesi di progettazione astratta. seguito da un elenco di probabili problemi e delle loro risoluzioni, seguito da una sezione più lunga con informazioni su come funziona un sistema, perché lo fa in questo modo e altre informazioni utili per indirizzare le persone nella giusta direzione nel caso dovesse accadere qualcosa di unico.
Nel mio ultimo lavoro ci è stato richiesto di scrivere doc in modo che anche le persone dell'helpdesk di livello 1 potessero riportare le cose. Ciò ha richiesto liste di controllo, che in genere sono diventate obsolete entro 3 mesi dalla scrittura. Siamo stati fortemente invitati a scrivere guide per la risoluzione dei problemi ogni volta che è possibile, ma quando l'albero di contingenza contiene più di tre rami, non è possibile scrivere quel documento senza diventare astratto.
Quando ho lasciato il mio ultimo lavoro, ho consegnato in 100 pagine il manuale "come fare il mio lavoro" prima di partire. Conteneva elementi astratti, filosofia di progettazione e punti di integrazione. Dato che presumibilmente stavo scrivendo per un altro amministratore di sistema che mi avrebbe sostituito, l'ho puntato su qualcuno che potesse prendere concetti astratti e trasformarli in azioni concrete.
Sono passati cinque anni e trovo che la mia opinione al riguardo sia leggermente cambiata. Sia Document as Manual che Document as Checklist hanno posti molto preziosi nella gerarchia della documentazione ed entrambi devono essere prodotti. Tuttavia, si rivolgono a un pubblico molto diverso.
Documento come lista di controllo
Il mercato target per questo tipo di documentazione sono i colleghi che vogliono sapere come fare una cosa. Vengono in due tipi:
- Collaboratori che vogliono solo sapere come fare una cosa e non hanno il tempo di sfogliare un manuale di quindici pagine e capire i passi da soli.
- Procedure che sono abbastanza complesse nei passaggi, ma devono essere eseguite solo una volta ogni tanto.
L'impazienza è il driver per il primo tipo. Forse il tuo collega in realtà non vuole sapere perché l'output deve essere reindirizzato attraverso una regex perl di 90 caratteri, solo che deve essere per chiudere il ticket. Includi sicuramente un'affermazione del tipo "Per una spiegazione dettagliata del perché questo flusso di lavoro si presenta così, segui questo link" nell'elenco di controllo per coloro che vogliono sapere il perché.
Il secondo punto riguarda le procedure che non vengono eseguite spesso ma contengono insidie. L'elenco di controllo funge da mappa per evitare che il Certo Destino si limitasse ad alarlo. Se la checklist è conservata in un repository di documentazione, evita di dover cercare e-mail per il tempo in cui il vecchio amministratore ha inviato un HOWTO.
A mio avviso, una buona documentazione della checklist include anche sezioni su possibili punti di errore e risposte a tali errori. Questo può rendere il documento piuttosto grande e innescare le risposte TL; DR nei colleghi, quindi trovo che rendere le modalità di errore e le loro risposte un collegamento dall'elenco di controllo piuttosto che sulla pagina stessa costituisca un elenco di controllo non spaventoso. Abbraccia l'ipertestualità.
Documento come manuale
Il mercato target per questo tipo di documentazione sono le persone che vogliono saperne di più su come funziona un sistema. La documentazione di stile come fare dovrebbe essere derivata da questa documentazione, ma più comunemente la vedo come un supplemento alla documentazione di stile checklist per il backup delle decisioni prese nel flusso di lavoro.
Questa è la documentazione in cui includiamo pezzi gommosi come:
- Spiegare perché è configurato in questo modo.
- Questa sezione può includere tali problemi non tecnici come la politica che circonda il modo in cui l'intera cosa è stata acquistata e installata.
- Spiegare le modalità di errore comuni e le loro risposte.
- Spiegare eventuali accordi a livello di servizio, sia scritti che di fatto.
- Di fatto: "se questo fallisce durante la settimana delle finali è un problema di caduta di tutto. Se durante le vacanze estive, torna a dormire e gestisci la mattina".
- Definizione degli obiettivi di aggiornamento e refactoring.
- La politica potrebbe essere diversa in seguito, perché non risolviamo alcune delle cattive idee introdotte all'inizio?
Che sono tutti molto utili per ottenere una comprensione globale di tutto il sistema. Non hai bisogno di una comprensione completa per eseguire semplici compiti di automazione umana, ne hai bisogno per capire perché qualcosa si è rotto in quel modo e hai idea di dove farlo non farlo di nuovo.
Hai anche menzionato la documentazione di Disaster Recovery che deve essere una lista di controllo.
Capisco, hai le mie simpatie.
Sì, la documentazione DR deve essere il più possibile simile a una checklist.
Sì, la documentazione DR è la più resistente all'elenco di controllo a causa di quanti modi in cui le cose possono rompersi.
Se la tua lista di controllo DR è simile a:
- Chiama Dustin o Karen.
- Spiega il problema.
- Stai indietro.
Hai un problema. Questa non è una lista di controllo, è un'ammissione che il ripristino di questo sistema è così complesso che un architetto deve capire. A volte è tutto ciò che puoi fare, ma cerca di evitarlo, se possibile.
Idealmente la documentazione di DR contiene liste di controllo delle procedure per alcune cose diverse:
- Procedure di triage per capire cosa è andato storto, che aiuteranno a identificare ...
- Procedure di recupero per alcuni casi di fallimento. Quale è supportato da ...
- Script di recupero scritti molto prima per aiutare a ridurre al minimo l'errore umano durante il recupero.
- Documentazione manuale sui casi di errore, sul motivo per cui si verificano e sul loro significato.
Le procedure di triage sono a volte tutta la documentazione DR che è possibile creare per alcuni sistemi. Ma averlo significa che il call-out delle 4am sarà più comprensibile e l'ingegnere senior che esegue il ripristino sarà in grado di affrontare il problema reale più velocemente.
Alcuni casi di fallimento hanno procedure di recupero dirette. Documentali. Durante la loro documentazione potresti trovare casi in cui vengono inseriti elenchi di comandi in un ordine specifico, che è un ottimo caso d'uso per gli script; può trasformare una procedura di recupero di 96 punti in una di 20 punti. Non capirai mai se riesci a scrivere qualcosa fino a quando non esegui la mappatura della procedura di recupero azione per azione.
La documentazione di tipo manuale per i casi di errore è l'ultimo backstop da utilizzare quando NON SONO presenti procedure di ripristino o procedure di ripristino non riuscite. Fornisce i suggerimenti di Google necessari per trovare qualcun altro che ha avuto quel problema e cosa ha fatto per risolverlo.