Come evitare che la documentazione del server non sia sincronizzata con la configurazione effettiva?

Abbiamo una documentazione abbastanza buona per il nostro ambiente (in formato AsciiDoc) che recentemente ha permesso a un'altra persona di ricreare l'intera installazione da zero in meno di 30 minuti.
Tuttavia, ho notato che dopo l'installazione iniziale, capita facilmente che piccole modifiche apportate al sistema (diciamo: inetd viene disattivato, il mio server IMAP è in ascolto su una porta aggiuntiva per le connessioni ManageSieve, un nuovo router viene aggiunto alla configurazione exim) don non finire immediatamente nella documentazione (se non del tutto).

La mia idea era di evitare questo problema generando (parzialmente?) La documentazione dai file di configurazione e i commenti in essi - un modo per implementare questo potrebbe essere quello di mettere /etce /usr/local/etcin un sistema di gestione del codice sorgente (diciamo - git) e quindi eseguire un script che rigenera la documentazione su ogni commit. Tuttavia, non sono sicuro che ciò sia eccessivo e / o troppo difficile da correggere (dopotutto, non voglio copie complete dei file di origine nella mia documentazione ma piuttosto solo le differenze).

In che modo altre persone evitano che la documentazione del server sia obsoleta? Esiste un buon modo per mantenerli sincronizzati automaticamente o hai la disciplina per aggiornare la documentazione nello stesso momento in cui modifichi il sistema?

Non riuscirai mai a sfuggire ad alcuni documenti ma, come hai intuito, ci sono sistemi che possono essere integrati nel tuo processo di modifica per coprirne molti.

• Utilizzare uno strumento di gestione della configurazione (come burattino o cuoco ).
• Memorizza la tua configurazione in modo controllato dalle modifiche. (come git o SVN )
• Assicurarsi che la configurazione sia leggibile / accessibile dall'uomo (es. Testo semplice, db ricercabile)

In questo modo la documentazione di livello inferiore che normalmente ci manca (o che non ci preoccupiamo) viene applicata archiviando le informazioni di distribuzione in elementi di configurazione o codice come parte del sistema in cui si apportano modifiche. Questo ha anche un ulteriore vantaggio del processo che diventerà più ripetibile in futuro.

La documentazione esterna deve ancora essere aggiornata, ma diventa di altissimo livello con i puntatori a "deploy x" o "deploy y" invece di lunghi elenchi di comandi / file. Ciò rende inoltre le modifiche alla documentazione meno frequenti e più facili, il che significa anche che sarà più probabile che vengano eseguite.

Anche prima di andare a fare la birra a casa, con il burattino qualcuno probabilmente ha già scritto qualcosa per gestire ciò che vuoi.

Se gestisci solo uno o due piccoli sistemi, impostare un grande sistema di gestione della configurazione come burattino o cuoco sembra eccessivo. (Tuttavia, se hai intenzione di avere più sistemi in futuro, fallo ora!)

Per una piccola configurazione come questa, consiglierei di usare qualcosa di simile etckeeper, un programma che inserisce /etcin un gitrepository e fornisce alcune funzioni utili, come eseguire un commit automatico ogni volta che installi, aggiorni o rimuovi un pacchetto.

Devi solo aggiornare la tua documentazione ogni volta che apporti una modifica al sistema. AKA Change Management.

Il fatto che la maggior parte delle aziende attui la gestione del cambiamento in modo così ridicolo da renderlo peggiore di niente non dovrebbe sminuire l'utilità del concetto di base o impedirti di farlo nel modo giusto.

Ho usato per usare htmlo una sorta di wiki per tenere traccia di tutte le mie configurazioni. Ora lavoro in un negozio di Windows con ( shudder ) SharePoint, quindi ora uso i "modelli" di documenti Word che ho creato per tenere traccia di tutti i sistemi che ho e di tutte le modifiche alla configurazione che faccio, il che non è male come sembra, dato che molti i sistemi sono solo copie di altri cookie che possono essere raggruppati nello stesso documento. (E conservo copie locali di tutti i miei documenti personali sul mio disco rigido, in realtà organizzati in modo ragionevole, oltre a gettarli sull'heap non organizzato che è il sito di SharePoint di chiunque.)

La sfida più grande è davvero quella di dedicare del tempo alla documentazione, cosa che faccio aggiungendo il tempo di documentazione come parte del tempo per apportare la modifica. Quindi, non è poi così difficile, soprattutto se sei un po 'un cretino e non ti dispiace dire alla gente di svignarsela e aspettare in fila perché al momento sei troppo occupato per il loro problema.