Manutenzione duplicata - codice e documentazione [chiuso]

Question

Questo potrebbe non essere il miglior titolo - lo apprezzerei se qualcuno ne trovasse uno migliore dopo aver letto il mio problema. Inoltre, voglio dire in anticipo che sono ampiamente autodidatta su Internet, quindi potrebbero esserci molti strumenti di cui non sono a conoscenza.

Sto mantenendo il software che implementa il concetto di programmazione basata sul flusso (FBP) sia in Java che in C #. Per ognuno di questi, ho il codice su:

• il mio sito web
• Sistema di rilascio file SourceForge (file zip o file jar)
• SourceForge SVN

Inoltre, ho riferimenti di versione e descrizioni (a volte parziali) su:

• il mio sito web (HTML)
• il mio wiki
• Javadoc

Esiste anche uno strumento di disegno, anche sul mio sito Web e su SourceForge, che deve conoscere l'ultima versione della versione Java del codice FBP.

Tutto è reticolato abbastanza accuratamente, ma a volte mi manca un riferimento! Qualche giorno fa, mi sono reso conto di non aver aggiornato SourceForge News per il mio progetto da molto tempo, quindi ho dovuto affrettarmi e farlo :-)

Mi rendo conto che alcuni di questi veicoli sono probabilmente ridondanti, ma in genere non so chi stia guardando cosa.

Quindi la mia domanda è se esiste un modo per ridurre tutto questo sovraccarico, ad es. un HTML "incorporato" la funzione sarebbe utile, quindi posso almeno memorizzare l'ultimo numero di versione in un unico posto. Probabilmente posso semplificare i riferimenti incrociati di Java, ma l'inter-lingua sarebbe ancora più bella, ma è improbabile, immagino.

Qualsiasi idea sarebbe benvenuta.

Answer 1

Mi sembra che tu voglia aggiornare e conservare la tua documentazione come parte del tuo processo di compilazione / distribuzione, ad esempio

1. costruire
2. unit test etc
3. compila documentazione
4. distribuisci build
5. distribuisci documentazione compilata

altrimenti stai sempre inseguendo la coda. Ovviamente la distribuzione della documentazione richiederà diverse soluzioni su dove sta andando (ad es. Copiata sul tuo sito web, inviata via FTP altrove ecc.)

Non sono sicuro che ci sia una panacea per tutto questo. Conservo i numeri di versione nei file delle proprietà / dei file di configurazione e eseguo ricerche / sostituzioni appropriate. La documentazione del codice, ove possibile, viene inserita nel codice stesso, quindi viene preelaborata nella mia build (passaggio 3 sopra).

Hai visto / usato doxygen ? Questo gestirà i tuoi requisiti multilingue ed è ben consolidato per la costruzione / manutenzione della documentazione.

Answer 2

Sembra che tu debba automatizzare il tuo processo di compilazione / pubblicazione. Ho letto questo articolo su O'Reilly qualche tempo fa - sembra che entrambi abbiate situazioni piuttosto simili? La sua soluzione fa ampio uso di Python, ma almeno potrebbe darti alcune idee.