Come scrivere correttamente un'installazione o un documento di installazione

Naviga le tue risposte
1

Sono appena entrato in una piccola start-up come ingegnere del software dopo la laurea. Lo start-up ha 4 anni e sto lavorando con il CEO e il COO, anche se ci sono alcune persone all'estero. Fondamentalmente entrambi facevano quasi tutto. Sono attualmente in una sorta di fase di addestramento. Ho a disposizione la documentazione interna di architettura, installazione e installazione. La documentazione di architettura è come una bibbia e dovrebbe contenere informazioni complete. Il resto è usato per dare indicazioni in diversi processi.

Il problema è che questi documenti sono più o meno datati, in quanto non hanno avuto il tempo di cambiarli. Mi occuperò dell'allenamento delle prossime assunzioni e l'aggiornamento di questi documenti è parte della mia formazione. In alcuni ci sono molte informazioni codificate come: 

 Install this_module_which_still_exists
     cd this_dir_name_changed
     cp this_file_name_changed other_dir_name_changed
     ./config_script.sh 
     ./execute_script.sh

I problemi che ho affrontato:

  • O l'installazione del modulo è completamente diversa (ad esempio ora c'è un rpm o un sistema operativo diverso)
  • Entrambi i nomi sono cambiati e ho bisogno di cambiare i vecchi nomi con nuovi nomi
  • Descrizione dello scopo del passaggio corrente mancante.
  • Mancano le informazioni su un intero argomento

Fortunatamente questi ragazzi sono in giro e ricevo tutte le informazioni che desidero e tutte le spiegazioni di cui ho bisogno. Voglio portare un disegno ai prossimi documenti, quindi in futuro le persone non si sentiranno come se stessero riscrivendo completamente un documento ogni volta che lo aggiornano.

Hai suggerimenti? Se esiste una metodologia di progettazione leggera disponibile online, puoi indicarmi anche il suo aspetto.

Una cosa che farò di sicuro è impostare un repository di versioning solo per i documenti. Ce n'è già uno per il codice sorgente, quindi non so perché i documenti interni meritino un trattamento diverso.

    
posta UmNyobe 06.09.2012 - 18:47
fonte

2 risposte

4

Tecnicamente, penso che una buona piattaforma wiki sia la scelta migliore per la maggior parte di questo tipo di documentazione. Facile da raggiungere, facile da compilare, una buona ricerca e la cronologia delle versioni sono tutte ottime funzionalità per questa attività. Esattamente quale piattaforma non è importante - correrei con tutto ciò che è in atto prima.

Il miglior consiglio che ho sentito su questo genere di cose è che le persone più esperte nel negozio dovrebbero scriverlo, e le persone meno esperte nel negozio dovrebbero testarlo in modo da poter trovare ciò che il team guida saltare.

    
risposta data 06.09.2012 - 18:56
fonte
0

Bene, penso che il vero problema è che vuoi che il tuo documento di installazione sia aggiornato. Questo non è niente che tu possa veramente risolvere migliorando il design del documento. Qualcuno deve essere responsabile di questo, ad esempio, gli sviluppatori del sistema ogni volta che cambiano qualcosa che influenza l'installazione.

Naturalmente, le probabilità che qualcuno si occupi di questo sono molto più alte quando la descrizione dell'installazione è molto piccola, quindi quello che @kevincline ha scritto nel suo commento è un passo nella giusta direzione: creare script o procedure di installazione che richiedono il minor numero di utenti interazione possibile. Un semplice file "readme" dovrebbe essere sufficiente - idealmente, non hai bisogno di alcuna descrizione di installazione, perché devi solo iniziare il tuo script di "configurazione" che fa tutte le cose giuste.

Tuttavia, se si sposta la descrizione dell'installazione in script di installazione, è necessario mantenere tali script aggiornati, il che di fatto sposta il problema da un supporto all'altro. Qualcuno deve effettivamente testare quegli script di installazione su base regolare e risolvere i problemi non appena si verificano. Ovviamente, avere un solo script di installazione per un programma ha il vantaggio che l'installazione può essere testata con molto meno sforzo manuale.

    
risposta data 06.09.2012 - 21:04
fonte

Leggi altre domande sui tag

Servlet: uso di Constants.java class vs context param Qual è il modo più veloce e preferibile per l'assegnazione di variabili in ruby? [chiuso]