Come mantenere la documentazione aggiornata e accessibile [duplicato]

Quello che devi fare è sviluppare un'unica fonte di informazioni .

A seconda degli strumenti e dei processi che usi, probabilmente non ne hai bisogno in tutti questi posti. Non sono sicuro di quali siano i requisiti per la documentazione, ma probabilmente guiderò quale strumento utilizzi come unico punto di riferimento. In minima parte, dovresti iniziare a raccogliere tutto elettronicamente e renderlo generalmente disponibile al team: estrarlo dalla carta fisica e in fonti elettroniche che sono ricercabili, indicizzate e sottoposte a backup.

Da lì, decidi i migliori metodi di acquisizione delle informazioni per le tue esigenze.

Purtroppo, poche organizzazioni riescono effettivamente a curare e quindi a mantenere la documentazione accessibile e aggiornata.

Sono un ingegnere a contratto che ha lavorato per oltre 120 società distinte, alcune delle quali conosci.

Le aziende di grandi dimensioni (oltre 50.000 dipendenti) potrebbero non avere standard o sistemi per la documentazione. Oppure hanno un sistema oneroso e di taglia unica. Né funziona molto bene nella pratica. Il primo perché non viene fatto. Quest'ultimo perché la difficoltà di fornire una scrittura utile è alta e l'aggiornamento è ancora più doloroso.

Le piccole aziende (meno di 50 dipendenti), in media, svolgono un lavoro molto migliore per richiedere e mantenere la documentazione interna ed esterna per il software per computer. Prendo atto che la migliore documentazione è il sapore interno scritto dall'ingegnere e inserito nel codice sorgente al momento della scrittura del codice. Gli strumenti di estrazione automatica incoraggiano in modo efficace questa pratica seguita.

Anche i progetti di una o due persone di solito fanno un buon lavoro nel conservare la documentazione insieme al codice sorgente e mantenerla rilevante.

Il software open source ha forse i migliori esempi funzionali. Guarda il kernel Linux : le informazioni relative all'architettura e alle istruzioni fanno parte di repository git e appare nella sottocartella Documentation/ nella radice del progetto.

Apporta l'aggiornamento dei vari documenti parte della tua "definizione di fatto".

Supponendo che stai usando metodi agili, il tuo lavoro sarà suddiviso in attività. Qualsiasi modifica alla documentazione primaria (il codice) probabilmente innescherà la necessità di modifiche a documenti integrativi (test, voci wiki, commenti, diagrammi, documenti di parole, ecc.). Pertanto, come parte dell'attività, la persona assegnata dovrebbe aggiornare i documenti interessati e tali documenti dovrebbero essere verificati come parte delle revisioni delle modifiche apportate da tale attività. Solo una volta che tutto (non solo il codice) viene aggiornato, controllato, esaminato e testato, nel caso in cui l'attività sia considerata completa.

@ThomasOwens ha menzionato la parte più importante, Sorgente singola

Quindi dovresti iniziare,

• Aggiunta di tutti i nuovi documenti a una singola fonte,
• Quando esegui le pianificazioni, aggiungi sposta la documentazione corrente alla nuova fonte alla lista delle cose da fare. Spendere un tempo separato per spostare tutti i documenti da una singola fonte all'altra è difficile, ma le persone possono aggiornare i documenti quando poi mantengono il servizio correlato, aggiornano la relativa base di codice, hanno bisogno del documento ma hanno difficoltà a trovare o un altro dipendente può avere difficoltà trovare documenti. Fare la mossa e unire le cose quando hai a che fare con il documento o il servizio correlato è più facile.

Puoi anche avere un sistema di origine distribuito gestito da un unico luogo!

• Puoi avere un server di documenti, inserire tutti i documenti lì. Qualunque cosa tu possa avere uno script che gira ogni mezzanotte e ispeziona i file, creando directory wiki e titoli wiki in base alla struttura di cartelle / file e aggiorna le pagine wiki secondo i file correlati usando i nomi dei file.
• È possibile avere uno strumento di documentazione basato sul Web dove si preparano e aggiornano i documenti su un software e il software può creare / aggiornare documenti (su dischi rigidi) su macchine locali o remote, aggiornare pagine wiki ecc.

Se sei riuscito a conservare tutti i tuoi documenti nello stesso posto, puoi distribuire le copie di sola lettura ovunque desideri.