Documentazione As-A-Manual vs. Documentazione As-A-Checklist

Ho avuto discussioni in passato con altre persone del mio dipartimento sulla documentazione, in particolare, livello di dettaglio e requisiti. Secondo loro, la documentazione è una semplice list di controllo delle cose Y da fare quando le cose X vanno male.

Non sono d'accordo. Penso che questo presupponga che tutte le questioni in IT possano facilmente essere bollite verso semplici liste di controllo delle procedure di recupero. Penso che ignora completamente la complessità della situazione e come le altre persone del dipartimento non hanno sempre una profondità di comprensione circa la questione (ecco perché scrivo il documento) per cui hanno qualcosa da fare riferimento ) che la documentazione dovrebbe includere alcuni materiali di base di base, quali:

  • Dolore rimuovendo un rootkit perl
  • Ripristino nudo di server Linux con Tivoli
  • Come posso redirect lo stdout / stderr di un process già in esecuzione?
  • Come si ripete quando il provider di hosting perde tutto?
  • Smontare un mount nfs in cui il server nfs è scomparso
  • Sql Backup differenziale server: model semplice vs completo recupero
    • Scopo del sistema (sottosistema) in questione
    • Perché è configurato in questo modo
    • Le aspettative di events che si verificano quando vengono implementate le impostazioni / procedure
    • Potenziali problemi che possono causare la mancata esecuzione delle procedure

    Tuttavia, sono piuttosto outvoted su questo, quindi la mia documentazione è necessaria per essere ri-scritto in una forma che dice "I passaggi ABC applicati in ordine risolverà il problema X". Sento spesso il lamento che deve adattarsi a una sola pagina di carta. Prova a spiegare a qualcuno la configuration di ACL di Squid in questo modo, inclusa la risoluzione dei problemi, attraverso un documento a una pagina. Questa è solo una delle dozzine di documenti che sono "in attesa di essere scritti" come liste di controllo di recupero.

    È il metodo che sto sostenendo di andare davvero a bordo? O sono giusti, e dovrei solo pensare al mio lavoro qui e basta scrivere loro una semplice list di controllo? La mia preoccupazione è che, non import quanto bene scrivi una list di controllo di procedura, non risolve davvero un problema che richiede a SysAdmin di pensare le cose. Se stai passando del tempo a fare una list di controllo delle procedure di recupero che finisce per non risolvere il problema (perché ci sono fattori aggiuntivi che non sono parte del documento, a causa della finezza del documento ) e lo scopo del documento il documento era quello di evitare di leggere di nuovo le pagine di uomo, i wiki e i siti web, perché dovrei attraversare i moti? Sto solo preoccupando troppo, o è un vero problema?

    EDIT:

    Al momento non ci sono posizioni di helpdesk nel dipartimento. Il pubblico per la documentazione sarebbe per gli altri amministratori o per la direzione del reparto.

    9 Solutions collect form web for “Documentazione As-A-Manual vs. Documentazione As-A-Checklist”

    Quando scrivo la mia, ho sempre devoluto a scrivere due tre set. La list di controllo "get-er-done", con una appendice MUCH LONGER sull'architettura del sistema, comprendente il motivo per cui le cose sono fatte nel modo in cui sono, probabili punti di attacco quando vengono in linea e assunzioni di progettazione astratta. seguita da un elenco di problemi probabili e nelle 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 indicare le persone nella giusta direzione.

    Al mio ultimo lavoro ci è stato richiesto di scrivere doc in modo che anche le persone di aiuto di livello 1 potrebbero portre le cose. Questo elenco di controllo richiesto, che generalmente è scaduto entro 3 mesi dalla scrittura. Siamo stati fortemente invitati a scrivere guide di risoluzione dei problemi quando ansible, ma quando l'tree di contingenza ottiene più di tre rami in esso, non puoi semplicemente scrivere quel documento senza andare astratto.

    Quando ho lasciato il mio ultimo lavoro, ho fatto una pagina di 100 pagine "come fare il mio lavoro" prima di partire. Aveva le cose astratte, la filosofia di progettazione, così come i punti di integrazione. Dal momento che presumibilmente scrivevo per un altro sysadmin che mi avrebbe sostituito, l'avrei rivolto a qualcuno che avrebbe potuto prendere nozioni astratte e trasformarle in azioni concnetworking.


    Sono passati cinque anni e ritengo che il mio parere su questo sia cambiato in qualche modo. Entrambi i documenti come manuale e documento come checklist hanno posti molto preziosi nella gerarchia della documentazione e entrambi devono essere prodotti. Essi tuttavia mirano a un pubblico molto diverso.

    Documento come elenco di controllo

    Il mercato di riferimento di questo tipo di documentazione è colleghi che vogliono come fare una cosa. Sono due tipi:

    • Collaboratori che vogliono solo sapere come fare una cosa e non hanno il tempo di pizzicare un manuale di quindici pagine e calcolare i passi per se stessi.
    • Procedure che sono abbastanza complesse nei passaggi, ma devono essere eseguite solo una volta.

    L'impazienza è l'autista per il primo tipo. Forse il tuo collega in realtà non vuole sapere perché l'output deve essere condotta attraverso una perl regex di 90 caratteri, solo che deve essere per chiudere il biglietto. Definitivamente includere un'istruzione come, "Per una spiegazione dettagliata del perché questo stream di lavoro sembra questo, segui questo collegamento", nella list di controllo per coloro che vogliono sapere perché.

    Il secondo punto è per le procedure che non vengono eseguite spesso ma contengono insidie. La list di controllo agisce come una mappa per evitare che la certa fatica di averlo appena alato. Se la list di controllo è mantenuta in un repo di documentazione, esso salva wherer ricercare la posta elettronica per il tempo in cui il vecchio amministratore ha inviato un HOWTO.

    A mio parere la buona documentazione di controllo comprende anche sezioni sui possibili punti di arresto e risposte a tali fallimenti. Ciò può rendere il documento piuttosto grande e innescare le risposte di TL alle collaboratrici, per cui trovo che rendere i modi di fallimento e le loro risposte un collegamento dalla list di controllo, piuttosto che sulla pagina stessa, crea una checklist unscary. Abbracciare l'ipertestualità.

    Documento come manuale

    Il mercato di riferimento di questo tipo di documentazione è la gente che vuole saperne di più su come funziona un sistema. La documentazione di tipo "come-da-fare-qualcosa" dovrebbe essere in grado di derivare da questa documentazione, ma più comunemente lo vedo come un supplemento alla documentazione di stile di controllo per eseguire il backup delle decisioni fatte nel stream di lavoro.

    Questa è la documentazione in cui includiamo tali pezzi chewy come:

    • Spiegando perché è configurato in questo modo.
      • Questa sezione può includere questioni non tecniche come la politica che circonda l'acquisto e l'installazione dell'intera cosa.
    • Spiegando le modalità comuni di fallimento e le loro risposte.
    • Spiegare tutti i contratti di livello di servizio, scritti e de facto.
      • De facto: "se questo fallisce durante la finale della settimana è un problema di goccia – tutto il problema. Se durante la pausa estiva, tornare a dormire e trattare la mattina."
    • Impostazione degli obiettivi di aggiornamento e rielaborazione.
      • La politica potrebbe essere diversa in seguito, perché non correggiamo alcune delle cattive idee che sono state introdotte all'inizio?

    Questi sono tutti utili per get una comprensione completa di tutto il sistema. Non hai bisogno di una comprensione completa per eseguire semplici compiti di automazione umana, devi capire perché qualcosa ha rotto il suo modo di fare e avere un'idea where farlo non farlo più.


    Hai anche citato la documentazione di disaster recovery che deve essere una list di controllo.

    Capisco, hai le mie simpatie.

    Sì, la documentazione DR deve essere il più ansible come ansible.
    Sì, la documentazione DR è la più resistente alla list di controllo a causa di quanti modi le cose possono rompere.

    Se la tua list di controllo DR è simile:

    1. Chiama Dustin o Karen.
    2. Spiega il problema.
    3. Stai indietro.

    Hai un problema. Questa non è una list di controllo, che è un ammissione che il recupero di questo sistema è così complesso che richiede un architetto a capire. A volte è tutto ciò che puoi fare, ma cerchi di evitarlo se è ansible.

    Idealmente la documentazione DR contiene procedure di controllo delle procedure per alcune cose diverse:

    • Procedure triage per capire cosa è andato storto, che aiuterà a identificare …
    • Procedure di recupero per alcuni casi di guasto. Che è supportto da …
    • Script di recupero precedentemente scritti per ridurre al minimo l'errore umano durante il recupero.
    • Documentazione manuale dei casi di guasto, perché si verificano e cosa intendono.

    Le procedure di triage sono a volte tutte le documentazioni DR che è ansible fare per alcuni sisthemes. Ma avendo questo significa che la chiamata 4am sarà più intelligibile e l'ingegnere senior che fa il ripristino sarà in grado di get più velocemente il problema reale.

    Alcuni casi di fallimento hanno procedure di recupero diretto. Documentali. Durante la loro documentazione si possono trovare casi in cui vengono elencati elenchi di comandi in un ordine specifico, che è un grande caso d'uso per lo script; può trasformare una procedura di recupero di 96 punti in un punto di 20 punti. Non potrai mai capire se puoi scrivere qualcosa fino a quando non pianificare l'azione della procedura di recupero per azione.

    La documentazione manuale per i casi di guasto è l'ultimo backstop di fucile da utilizzare se non ci sono procedure di recupero o le procedure di recupero non sono riuscite. Fornisce le indicazioni di google necessarie per trovare qualcun altro che ha avuto questo problema e cosa hanno fatto per risolvere il problema.

    In realtà né, noi utilizziamo Documentazione As-a-Testcase

    Detto questo, abbiamo scritto la documentazione che va con Documentazione As-a-Manual . Avevamo liste di controllo in vigore ma quando siamo cresciuti li abbiamo trovati errati e veramente falliti sul sistema nel suo complesso.

    Tuttavia abbiamo una sorta di "Documentation As-a-Checklist" installata, ovvero – come abbiamo detto in precedenza – controlliamo ampiamente i nostri servizi. C'è un detto:

    Se non lo stai monitorando, non lo gestisci

    Questo è così totalmente vero, ma un'altra dovrebbe essere:

    Se non lo stai monitorando, non lo stai documentando

    Ogni volta che abbiamo bisogno di migrare i servizi, manteniamo solo il "Gruppo di servizi", "Gruppo Host", qualunque cosa vada (si utilizza Nagios, come si può immaginare dal vocabolario) aperto e non viene migrato finché c'è un punto rosso singolo su uno qualsiasi dei servizi.

    I test forniscono una list di controllo molto migliore di qualsiasi elenco di controllo scritto a mano. In realtà è autodifesa, non appena abbiamo qualche fallimento che non è stato monitorato, il test verrà comunque aggiunto a Nagios, con cui otteniamo 2 cose gratuite:

    • sappiamo quando non riesce
    • un altro punto della list di controllo

    La documentazione "reale" viene mantenuta in un Wiki, menzionando le probabilità e le estremità del servizio o del test specifico. Se manca, la gente lo aggiungerà non appena abbiamo bisogno di fare una migrazione o abbiamo bisogno di fare qualche lavoro con esso, finora che l'approccio ha funzionato molto bene.

    Anche la documentazione erronica viene risolta veramente veloce, each volta che qualcosa non riesce a cominciare a cercare la documentazione e cercare di risolvere il problema con i HowTos in esso, se è sbagliato solo aggiornarlo con i tuoi risultati.

    Basta pensare agli errori che si potrebbero creare seguendo una list di controllo e non aver installato alcun test che vi darà una casella di controllo verde dopo averli applicati. Non credo sia ansible separare la documentazione dal monitoraggio.

    Dipende dal pubblico di destinazione per la documentazione.

    Per i tipi di helpdesk (livello 1), una list di controllo è il modo corretto di andare; 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 sisthemes, ho sempre errato sul lato di più documentazione. È abbastanza difficile avere una documentazione sufficiente per arrivare, se qualcuno (lei stesso) vuole scrivere documenti più estesi con le informazioni di base necessarie – nessun individuo sano dovrebbe stare al tuo posto!

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

    • Che cosa [X] dovrebbe fare (requisiti).
    • Come [X] è stato strutturato ad un livello elevato (design).
    • Perché ho implementato [X] nel modo in cui ho fatto (considerazioni di implementazione).
    • Come l'implementazione di [X] non è standard (soluzioni alternative).
    • Problemi comuni con [X] e come risolverli (problemi).

    Quindi la mia sezione di problemi comuni è probabilmente una breve descrizione di ciò che è accaduto e punti di puntamento su come risolvere il problema.

    Di solito assumo alcune conoscenze dal lettore del sistema in questione (a less che non sia particolarmente arcano). Non ho tempo per rendere la maggior parte della mia documentazione tecnica 1 o la gestione leggibile – ma un livello 3 fondamentale dovrebbe essere soddisfacente.

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

    Certamente suona come stai parlando di documentazione interna e nella mia esperienza non puoi solo dare un elenco di passi, perché ci sono troppe scelte. Anche la creazione di un account utente presenta alcune opzioni (nel nostro ambiente), quindi il nostro documento "Nuovo account" elenca i passaggi di base in ordine, ma per each passo ha una descrizione di quali sono le variazioni.

    D'altro canto, non siamo mai stati in giro per scrivere gran parte di un documento per "Come patch in un ufficio", ma anche il nostro documento molto scompigliato non era una list di controllo – ha menzionato la convenzione che abbiamo usato per i colors dei cavi, che wherevi aggiornare il foglio di calcolo che elencava le connessioni, e che era in questo caso.

    Quindi, adesso che ho scritto questo, sono del tutto d'accordo: le liste di controllo passo per passo non lo taglieranno per molti processi.

    Sono fortemente d'accordo con voi su questo (a favore della documentazione esaustiva) in parte perché sono abituato ad avere i predecessori che NON hanno molto interesse per i docs a tutti. Come è stato detto nei post correlati, la scrittura non è solo buona per gli altri, ma ti aiuta a comprendere meglio il tuo ambiente e consolidarlo nella tua mente. È una fine a se stessa.

    Come da parte, ritengo che un sacco di pushback deriva da una strana credenza che documentazione crappy / nonexistant = sicurezza del lavoro. Quel tipo di pensiero sembra solo disonesto e ombreggiato.

    Kudos a te per aver sconfitto lo status quo.

    Documento molto, ho anche una list di controllo prioritaria del documento :-), tuttavia non documenterò cose che possano essere considerate conoscenze generics (ad esempio una buona descrizione ragionevole del problema fornisce una risposta nella prima pagina di google).

    Per chiunque sia interessato qui è la mia list di documenti doc (funziona per me, potrebbe non essere per voi, commenti e suggerimenti sono molto apprezzati):

    1. Crea un registro / diario personale che scrivi tutto ciò che hai fatto per lavorare / conoscenza saggia
    2. Servizi, quale servizio è where, cosa fa e per chi è fatto (eventuali accordi SLA? Si dovrebbe creare uno?)
    3. Server, quale server è where, quanti anni e quando è scritto
    4. Come sopra ma per apparecchiature di networking, UPS e simili
    5. Come sopra ma per tutte le macchine utente
    6. Layout della networking fisica (quale cavo va where, per quanto tempo e qual è la qualità misurata)
    7. Panoramica di configuration del software e delle licenze per i server
    8. Panoramica di configuration del software e delle licenze per le macchine utente
    9. Panoramica di configuration degli switch, dei router e di altri hardware dedicati
    10. Contratti e SLA di tutte le parti esterne per cui dipende direttamente il mio servizio (ISP, dominio, ecc.)
    11. Impostare un sistema di biglietti con wiki integrato per mettere in esso tutte le cose di cui sopra.
    12. Per each incidente creare un biglietto (anche se lo si utilizza solo per il tuo).
    13. Creare uno script che in Domenica raccoglie i biglietti e li raggruppa sul tipo di problema.
    14. Lunedì crea una soluzione automatica o l'utente finale per documentare il problema più presente
    15. Se il tempo lo consente, fare quello successivo.
    16. Se non c'è altro da fare, cercare un nuovo lavoro e dare alla persona che ti sostituisce il log 😉

    Una list di controllo va bene, a patto che non si finge di essere una documentazione completa . Gli ultimi documenti che ho scritto sono venuti in due parti: XYZ for Users, che includeva gravi screenshot su come utilizzarlo; e XYZ per gli amministratori di sistema, che includevano come è stato configurato e perché (possibilmente anche il requisito aziendale per esistere), le trappole da evitare e una sezione sulla risoluzione dei problemi. La risoluzione dei problemi è where mi aspetto di trovare le liste di controllo. Forse scrivere le liste di controllo come XYZ per il supporto tecnico potrebbe contribuire a fare un punto.

    Ora, leggendo tra le righe, concentrandosi solo sulle liste di controllo mi indica una mancanza di pensiero e di pianificazione a lungo termine che mi aspettavo da qualcuno che: abbia mai fatto solo un supporto tecnico; o un amministratore junior appena cominciando; o è così sconvolto dal lavoro che non hanno tempo per pensarci; o non è mai stato spinto a pensarci; o semplicemente semplice non import. Non so quale di questi, se del caso, si applica nel tuo caso.

    Sono abbastanza grande nella documentazione. L'azienda in cui lavoro adesso sento che la documentazione è importnte, ma alcune persone della società sanno che non hanno tempo per scrivere la documentazione. Questo può rendere la vita difficile per chiunque, oltre alla persona che l'ha fatto in origine.

    Per alcune cose ho scritto istruzioni passo-passo. Puoi call questa list di controllo se vuoi, ma non è realmente intesa per essere verificata fisicamente. Chiamo la mia documentazione la "scuola materna". È modellato dopo un libro di esercitazione MCSE che ho avuto per uno degli esami di Windows 2000. I passaggi sono molto dettagliati, ma l'uso di grassetto / corsivo / tipo di carattere rende facile da lucidare e solo individuare le parti importnti in modo da non wherer leggere tutto dopo aver appreso i passaggi.

    Alcune cose non si prestano bene alle istruzioni passo passo, quindi cerco di fornire altretanto dati di configuration che posso. Una persona tecnicamente incline che finisce per mantenere la strada avrà un'idea migliore di quello che sono contro, e spero che la loro vita sarà un po 'più facile quando qualcosa va storto.

    Suggerimenti per Linux e Windows Server, quali Ubuntu, Centos, Apache, Nginx, Debian e argomenti di rete.