Documentazione come manuale A vs. Documentazione come lista di controllo


17

In passato ho avuto discussioni con altre persone nel mio dipartimento sulla documentazione, in particolare sul livello di dettaglio e sui requisiti. A loro avviso, la documentazione è un semplice elenco di controllo di Y cose da fare quando X cose vanno male.

Non sono d'accordo. Penso che ciò presuma che tutti i problemi nell'IT possano essere facilmente riassunti in semplici liste di controllo delle procedure di recupero. Penso che ignori completamente la complessità della situazione e poiché le altre persone del dipartimento non hanno sempre una comprensione approfondita del problema (motivo per cui sto scrivendo il documento - quindi hanno qualcosa a cui fare riferimento ) che la documentazione dovrebbe includere alcuni materiali di base di base, quali:

  • Scopo del (sotto) sistema in questione
  • Perché è configurato in quel modo
  • Aspettative di eventi che si verificano quando vengono implementate le impostazioni / procedure
  • Potenziali problemi che possono causare il fallimento delle procedure

Tuttavia, sono piuttosto contrario a questo, quindi la mia documentazione deve essere riscritta in un modulo che dice "I passaggi ABC applicati per risolvere il problema X". Sento spesso il lamento che deve adattarsi a una singola pagina di carta. Prova a spiegare a qualcuno la configurazione di ACL di Squid in questo modo, inclusa la risoluzione dei problemi, attraverso un documento a pagina singola. Questa è solo una mezza dozzina di documenti che "aspettano di essere scritti" come liste di controllo per il recupero.

Il metodo che sto sostenendo sta davvero esagerando? O hanno ragione, e dovrei solo occuparmi dei miei affari qui e scrivere loro una semplice lista di controllo? La mia preoccupazione è che, non importa quanto bene si scriva un elenco di controllo delle procedure, in realtà non risolve un problema che richiede un amministratore di sistema per riflettere. Se trascorri del tempo facendo un elenco di controllo delle procedure di recupero che finisce per non risolvere il problema (perché ci sono altri fattori che non fanno parte del documento, a causa della ristretta attenzione del documento ) e lo scopo del il documento era di evitare di rileggere di nuovo pagine man, wiki e siti Web, quindi perché sto esaminando i movimenti? Sto solo preoccupandomi troppo o è un vero problema?

MODIFICARE:

Attualmente non esiste alcuna posizione di helpdesk nel dipartimento. Il pubblico per la documentazione sarebbe per gli altri amministratori o per il capo dipartimento.


1
Per quanto riguarda la tua modifica: se il tuo capo dipartimento vuole capire ogni piccola informazione, probabilmente sta facendo enormi quantità di micro gestione. Dovresti parlargli di razionalizzare alcuni processi per assicurarti che almeno una persona sul posto possa lavorare con la documentazione fornita in qualsiasi momento. Non che capisca tutto.
serverhorror,

Risposte:


11

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:

  1. Chiama Dustin o Karen.
  2. Spiega il problema.
  3. 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.


Sembra molto simile all'ambiente in cui mi trovo (meno l'helpdesk). +1 per "perché l'ho fatto in quel modo"
Avery Payne,

@ sysadmin1138, hai dichiarato "Quando ho lasciato il mio ultimo lavoro, ho consegnato in 100 pagine il manuale" come fare il mio lavoro "prima di partire" . Perchè lo hai fatto? Questo è effettivamente richiesto? Altrimenti, perché preoccuparsi di un 100 pagine poiché stai già lasciando?
Pacerier,

1
@Pacerier Quello era ... 12 anni fa. Ed ero l' unico amministratore che copriva certe cose. Inoltre, quella compagnia mi è piaciuta, quindi ho voluto una consegna pulita. Altre società mi hanno bloccato in 2 settimane di "sessioni di condivisione delle conoscenze" che avevano lo scopo di fare lo stesso tipo di cose. Solo meno affidabile, poiché la memoria umana è davvero pessima.
sysadmin1138

don't have timepotrebbe essere don't have time. Esperienza complessiva e riutilizzabile!
n611x007,

14

In realtà neanche, usiamo Documentation As-a-Testcase

Detto questo, abbiamo scritto la documentazione che accompagna la documentazione come manuale . Avevamo creato delle liste di controllo, ma durante la crescita le abbiamo trovate soggette a errori e non funzionanti nel sistema nel suo complesso.

Abbiamo comunque installato una sorta di "Documentazione come lista di controllo", ovvero - come detto sopra - monitoriamo ampiamente i nostri servizi. C'è un detto:

Se non lo stai monitorando non lo gestisci

È così vero, ma un altro dovrebbe essere:

Se non lo stai monitorando non lo stai documentando

Ogni volta che abbiamo bisogno di migrare i servizi, teniamo semplicemente aperti il ​​"Gruppo di servizi", il "Gruppo host", qualunque cosa si applichi (usiamo Nagios, come puoi immaginare dal vocabolario) e non viene migrata finché c'è un singolo punto rosso su uno qualsiasi dei servizi.

I test forniscono una lista di controllo molto migliore di qualsiasi altra lista di controllo scritta a mano. In realtà si sta documentando da soli, non appena avremo qualche errore che non è stato monitorato, tuttavia il test verrà almeno aggiunto a Nagios, con quello otteniamo 2 cose gratis:

  • sappiamo quando fallisce
  • un altro punto della lista di controllo

La documentazione "reale" è contenuta in un Wiki in cui si menzionano le probabilità e i fini del servizio o test specifico. Se mancano le persone lo aggiungeranno non appena avremo bisogno di eseguire alcune migrazioni o dovremo lavorare con esso, finora l'approccio ha funzionato molto bene.

Inoltre, la documentazione errata viene risolta molto velocemente, ogni volta che qualcosa non riesce le persone iniziano a cercare la documentazione e cercano di risolvere il problema con gli HowTo lì dentro, se è sbagliato aggiornalo con i tuoi risultati.

Basti pensare agli errori che si potrebbero creare seguendo una lista di controllo e non avendo installato alcun test che ti darà una casella verde dopo averli applicati. Non credo sia possibile separare la documentazione dal monitoraggio.


2
+1 per un punto di vista alternativo.
Avery Payne,

2
Ho visto un video di YouTube pulito che mostra un sistema che esegue test di integrazione / accettazione e registra screencast. youtube.com/watch?v=78mts_sKNGs
jldugger

5

Dipende dal pubblico target per la tua documentazione.

Per i tipi di helpdesk (livello 1), una checklist è la strada giusta da percorrere; ovviamente, questo presuppone che ci siano livelli più alti di supporto con la conoscenza più profonda che descrivi.

Se la documentazione è per il gruppo di sistemi, sbaglio sempre dalla parte di più documentazione. È abbastanza difficile avere una documentazione adeguata solo per cavarsela, se qualcuno (te stesso) vuole scrivere documenti più estesi con le informazioni di base richieste - nessun individuo sano di mente dovrebbe ostacolarti!


+1 La documentazione deve essere sempre scritta tenendo presente il target di riferimento. Stanno leggendo il documento per ricavarne qualcosa ... è quella conoscenza o è come fare qualcosa. Se è come fare qualcosa che potrebbe richiedere un po 'di conoscenza extra, ho scoperto che mettere la conoscenza extra in un'appendice è un buon modo di procedere.
Paul Rowland,

5

Personalmente cerco di mantenere la documentazione il più semplice possibile. Tende a includere:

  • Cosa [X] dovrebbe fare (requisiti).
  • Come [X] è stata strutturata ad alto livello (design).
  • Perché ho implementato [X] come ho fatto (considerazioni sull'implementazione).
  • In che modo l'implementazione di [X] non è standard (soluzioni alternative).
  • Problemi comuni con [X] e come risolverli (problemi).

Quindi, è vero che la mia sezione sui problemi comuni è probabilmente una breve descrizione di ciò che è successo e punti dettagliati su come risolverlo.

Di solito presumo alcune conoscenze dal lettore del sistema in questione (a meno che non sia particolarmente arcano). Non ho tempo per rendere leggibile la maggior parte della mia documentazione tecnica di livello 1 o gestionale, ma un livello 3 chiaro dovrebbe andare bene.


4

Penso che ovviamente dipenda dall'argomento. Non tutto può essere ridotto a una semplice lista di controllo e non tutto ha bisogno di un manuale utente dettagliato.

Sembra certamente che tu stia parlando della documentazione interna e nella mia esperienza non puoi semplicemente dare un elenco di passaggi, perché ci sono troppe scelte. Anche la creazione di un account utente ha alcune opzioni (nel nostro ambiente), quindi il nostro documento "Nuovo account" elenca i passaggi di base in ordine, ma per ogni passaggio ha una descrizione di quali sono le variazioni.

D'altra parte, non siamo mai riusciti a scrivere gran parte di un documento per "Come rattoppare in un ufficio", ma anche il nostro documento molto abbozzato non era una lista di controllo - menzionava la convenzione che abbiamo usato per i colori dei cavi, ha sottolineato che si doveva per aggiornare il foglio di calcolo che ha elencato le connessioni, e che era su di esso.

Quindi, ora che ho scritto questo, sono totalmente d'accordo: le liste di controllo passo-passo non lo taglieranno per molti processi.


3

Sono pienamente d'accordo con te su questo (a favore di una documentazione esaustiva) in parte perché sono abituato ad avere predecessori che NON avevano alcun interesse per i documenti. Come è stato detto nel post correlati, scrivendo fuori non è solo un bene per gli altri, ma aiuta a capire più pienamente il proprio ambiente e consolidare nella vostra propria mente. È fine a se stesso.

A parte questo, trovo che gran parte del pushback provenga da una strana convinzione che la documentazione scadente / inesistente = sicurezza del lavoro. Questo tipo di pensiero sembra solo disonesto e ombroso.

Complimenti a te per aver ribaltato lo status quo.


3

Documento abbastanza, ho anche un elenco di controllo delle priorità dei documenti :-), tuttavia non documenterò elementi che possono essere considerati conoscenze generiche (ovvero una buona descrizione ragionevole del problema fornisce una risposta nella prima pagina di Google).

Per chiunque sia interessato qui è la mia lista di controllo doc prio (funziona per me, potrebbe non essere per te, commenti e suggerimenti sono molto apprezzati):

  1. Crea un diario / diario personale in cui annoti tutto ciò che hai fatto / conoscenza saggia
  2. Servizi, quale servizio è dove, cosa fa e per chi viene fatto (eventuali accordi SLA? Si dovrebbe creare?)
  3. Server, quale server è dove, quanti anni e quando è scritto
  4. Come sopra ma per apparecchiature di rete, UPS e simili
  5. Come sopra ma per tutte le macchine utente
  6. Layout della rete fisica (quale cavo va dove, quanto dura e qual è la qualità misurata)
  7. Panoramica della configurazione di software e licenze per server
  8. Panoramica della configurazione di software e licenze per macchine utente
  9. Panoramica della configurazione di switch, router e altro hardware dedicato
  10. Contratti e SLA di tutte le parti esterne per le quali il mio servizio dipende direttamente (ISP, dominio ecc.)
  11. Imposta un sistema di ticket con wiki integrato per inserire tutte le cose di cui sopra.
  12. Per ogni incidente crea un biglietto (anche se lo usi solo per te stesso).
  13. Crea uno script che domenica raccoglie i biglietti e li raggruppa in base al tipo di problema.
  14. Lunedì creare una soluzione automatica o come documentare l'utente finale per il problema più grave
  15. Se il tempo lo consente, fai il prossimo.
  16. Se non altro da fare, cerca un nuovo lavoro e dai alla persona che ti sostituisce il registro ;-)

1

Una lista di controllo va bene, purché non pretenda di essere documentazione completa . Gli ultimi documenti che ho scritto sono stati divisi in due parti: XYZ for Users, che includeva graziose schermate su come usarlo; e XYZ per amministratori di sistema, che includevano il modo in cui era stato impostato e perché (eventualmente includendo anche i requisiti aziendali perché esistessero), trappole da evitare e una sezione sulla risoluzione dei problemi. Risoluzione dei problemi è dove mi aspetto di trovare le liste di controllo. Forse scrivere le liste di controllo come XYZ per il supporto tecnico potrebbe aiutare a chiarire il punto.

Ora, leggere tra le righe, concentrarsi solo sulle liste di controllo mi indica una mancanza di pensiero "Big Picture" e di pianificazione a lungo termine che mi aspetterei da qualcuno che: ha mai fatto solo supporto tecnico; o un amministratore junior che ha appena iniziato; o è così sommerso dal lavoro che non ha tempo di pensarci; o non è mai stato spinto a pensarci; o semplicemente non importa. Non so quale di questi, se del caso, si applica al tuo caso.


L'override proviene principalmente dal capo dipartimento. Ma altri sono d'accordo. Mi attengo ancora alle mie pistole e scrivo il più possibile con quel poco tempo che mi rimane nel corso della giornata.
Avery Payne,

1

Sono abbastanza grande sulla documentazione. La società in cui lavoro ora ritiene che la documentazione sia importante, ma alcune persone ritengono di non avere il tempo di scrivere la documentazione. Questo può rendere la vita difficile a chiunque, a parte la persona che l'ha originariamente fatto.

Per alcune cose, ho scritto istruzioni dettagliate. Puoi chiamarlo una lista di controllo se vuoi, ma non è davvero destinato a essere spuntato fisicamente. Chiamo il mio stile di documentazione "passi dell'asilo". È modellato su un quaderno MCSE che ho avuto per uno degli esami di Windows 2000. I passaggi sono molto dettagliati, ma l'uso di grassetto / corsivo / carattere tipografico semplifica il gloss e seleziona le parti importanti in modo da non dover leggere tutto dopo aver appreso i passaggi.

Alcune cose non si prestano bene alle istruzioni dettagliate, quindi provo a fornire quanti più dati di configurazione possibile. Qualche persona tecnicamente incline che finirà per mantenere la strada avrà una migliore idea di ciò che stanno affrontando e, si spera, renderà la loro vita un po 'più facile quando qualcosa va storto.

Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.