Introduzione alla documentazione

Non abbiamo fatto alcuna documentazione sul mio posto di lavoro. Sono completamente nuovo e chiedo alcune indicazioni per iniziare.

Ho alcune domande:

• Quali sono i documenti essenziali che un amministratore di sistema dovrebbe scrivere e conservare? E perché sono così importanti?

• Come si sincronizza la documentazione con il sistema? Come ridurre al minimo la duplicazione delle informazioni?

• Guide consigliate, migliori pratiche, anti-schemi?

dal 2003 sto documentando tutto nel nostro wiki interno.

server

• specifiche hardware
• informazioni di garanzia
• informazioni di rete
• e ovviamente software e configurazione installati

Flussi di lavoro

ad es. come aggiungere o eliminare un utente e dargli accesso a tutti i servizi pertinenti

Link importanti

• collegamento a tutte le tue interfacce web
• collegamento agli URL di monitoraggio (nagios, munin, apc-monitoring ...)
• collegamento al wiki (per la versione stampata!)

Istruzioni di emergenza

cosa fare se il server intranet / internet / web server / ecc. sono inattivi

Importante:

Scegli un motore wiki con facile esportazione in PDF!
Non è utile se sei in vacanza, il server che esegue la tua wiki è inattivo e nessuno sa cosa fare perché la tua documentazione non è in linea

Dai un'occhiata a twiki, docuwiki o mediawiki.

BTW:

c'è un plugin OpenOffice.org per scrivere direttamente su mediawiki - molto conveniente.

MODIFICARE:

È anche bello scrivere alcune informazioni a /home/adminuser/maintenance. Questo viene fatto rapidamente e può essere molto utile se più amministratori lavorano su un server. per esempio:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Mentre ti rendi conto che mentre tutti vogliono (e hanno bisogno) della documentazione, devi anche riconoscere che nessuno ha il tempo di leggere e studiare le cose.

Quindi, non scrivere la documentazione che deve essere studiata - invece, strutturare la documentazione in modo tale da consentire a qualcuno di trovare rapidamente le informazioni di cui hanno bisogno, quando ne hanno bisogno - che potrebbe benissimo essere mentre il sistema è spento e il CTO è respirando giù per il collo.

Con questo in mente, alcuni suggerimenti ...

• Evita grandi blocchi di testo
• Gli elenchi puntati sono tuoi amici
• Un diagramma chiaro è dorato
• La ripetizione è una buona idea (1)
• Semplifica l'aggiornamento e l'estensione

(1) Non creare una fonte di verità e costringere le persone a cacciarla. Più importante è l'idea, più dovresti ripeterla.

Documenti essenziali:

• Documentazione del server - specifiche / layout del disco / software installato / nulla di rilevante
• Procedure comuni: tutto ciò che viene fatto che non è "banale" dovrebbe avere una procedura documentata, soprattutto se si tratta di qualcosa che non è mai stato fatto prima.

Mantenere la documentazione sincronizzata può essere praticamente una questione di "correzione come vedi errori". Insieme a ciò è necessario comprendere che la documentazione può e sarà obsoleta e che non dovrebbe essere seguita alla cieca senza tenerne conto. La documentazione è lì per aiutare un amministratore nelle attività, non per essere un insieme graduale di regole che sostituiscono il pensiero critico.

Ridurre al minimo la duplicazione: utilizzare qualcosa come i wiki in cui è possibile collegare la documentazione insieme può aiutare in questo, invece di ripetere le informazioni, basta collegarsi ad essa. Il problema è che la persona che scrive la documentazione deve sapere che le informazioni che stanno per duplicare esistono già. Di solito si tratta di una buona organizzazione.

Ho scoperto che la creazione di un modello è di grande aiuto. Nel mio caso è un modello di Word ma usa qualunque suite tu. Creare un file scheletro, completo di campo del sommario e sezioni come desiderato. Dopo averlo usato un paio di volte e aver apportato regolazioni di precisione, creerai nuovi documenti molto più velocemente. La coerenza del formato sarà di grande aiuto, sia per la creazione di documenti che per un uso successivo. La documentazione deve essere archiviata in un luogo logico e in una struttura di directory logica.

Sono personalmente contrario alla ripetizione per il semplice fatto che rende la manutenzione inutilmente difficile e richiede tempo. Invece di duplicare documenti o parti di documenti, creare riferimenti ad altri documenti, se del caso. Se qualcosa cambia non si dovrebbe mai essere necessario cambiare la relativa documentazione più di una volta o in più di un luogo, altrimenti si avrà una raccolta di documenti contrastanti, che aiuta nessuno.

Durante la creazione della documentazione, tieni a mente a cosa serve. Qualcuno in un secondo momento dovrà usarlo. Sarà utilizzabile svolgere il lavoro senza una conoscenza preliminare?

Non una risposta diretta alla tua domanda, ma un puntatore nella giusta direzione:

Ho trovato The Practice of System and Network Administration , di Limoncelli e Hogan (alias la Bibbia Sysadmin) per essere piuttosto preziosi perché si tratta di questioni relative alle "migliori pratiche", come la documentazione. Se non lo conosci già, assicurati di investigarlo ogni volta che ne hai la possibilità.

Per me, la considerazione più importante è renderlo facile da usare. Se è difficile orchestrare, le persone lo eviteranno. Ho scelto il wiki di Trac come supporto per la nostra documentazione per questi motivi:

• Situato in posizione centrale.

  Più di una copia attiva di ogni documento genera confusione. Se sei in grado di indirizzare tutti nello stesso posto, sia i collaboratori che il pubblico, puoi semplificare il processo.

• Modifica e formattazione semplici.

  Si spreca così tanto tempo su graziosi modelli di Word e conformi allo stile dell'ultimo autore. Se non impantoni le persone con questo, allora è più facile modificare in movimento e i collaboratori sono più propensi a farlo. Separa gli elementi quanto desideri con TracLinks.

• Cronologia degli audit.

  È importante sapere chi ha fatto ciò che cambia, quando e perché. Se puoi collegarlo ai ticket di richiesta di modifica e ai log di commit della configurazione, allora ancora meglio. Gli hook di commit SVN sono ottimi per questo.