I wiki sono davvero appropriati per archiviare documenti per lo sviluppo di software? [chiuso]

Tutti sanno che lo sviluppo di software ben documentato porta al successo. Tuttavia, di solito significa che non solo il testo normale ma anche il contenuto binario saranno coinvolti nel documento, come un diagramma UML. E ho sentito molte persone dirlo. Il sistema di controllo della versione non è il posto appropriato per i file binari. Capisco perfettamente e sono d'accordo con il problema. Ho chiesto a molti sviluppatori esperti dove fosse il posto migliore dove archiviare i documenti e la risposta che ho ricevuto è stata "wiki". Wiki è buono ma ho considerato un altro potenziale problema. Come può il codice sorgente che è stato memorizzato in un sistema di controllo della versione connettersi al suo documento correlato nel wiki? Diciamo che qualcuno clona il repository di git o mercurial. Come può facilmente trovare il documento? O ho appena perso qualcosa?

So che alcuni sistemi wiki hanno la capacità di integrarsi con i sistemi di controllo del codice sorgente. Ma la mia preoccupazione non riguarda la capacità di integrazione. Se hai clonato il codice sorgente da un repository git e dopo un po 'sali su un treno e vuoi continuare a lavorare offline sul treno (che è una grande caratteristica di DVCS). Poi improvvisamente ti rendi conto di non avere accesso al documento poiché lavori offline sul treno. D'altra parte, se il documento fosse archiviato nel repository git, avresti accesso al documento con il repository clonato.

WIKI è davvero appropriato per archiviare documenti per lo sviluppo di software?

Invece di scrivere documenti, pdf e altri tipi di file, perché non liberare tutto il potenziale del WIKI come strumento di collaborazione? Puoi scrivere i tuoi documenti lì, allegare i tuoi diagrammi e ancora meglio: se usi Fitnesse , puoi trasformare le tue pagine wiki in documenti davvero utili e vivi, in quanto possono diventare una specifica eseguibile.

Tutti sanno che lo sviluppo di software ben documentato porta al successo

Fai attenzione a questo. I documenti NON VERRANNO SUCCESSI, in quanto non trasformeranno il codice di merda in buono. Ma i documenti fanno parte del software di successo. Ma solo una parte e non sostituiranno le buone pratiche e le brave persone.

Poiché le risposte multiple indicano Trac come un suggerimento, vorrei suggerire un'alternativa simile, ma migliore secondo me, Redmine .

Redmine è una soluzione di gestione dei progetti, tra cui Wiki, Document Repository e integrazione di controllo versione. È anche scritto in Ruby on Rails e molto più facile da estendere e hackerare rispetto a Trac, nella mia esperienza.

Più di ogni altra cosa è davvero facile da usare ed è facile convincere il team a usarlo.

Caratteristiche:

• Supporto per più progetti
• Controllo degli accessi flessibile basato sui ruoli
• Sistema flessibile di localizzazione dei problemi
• Diagramma e calendario di Gantt
• Gestione di notizie, documenti e file
• Feed e notifiche e-mail
• Per progetto wiki
• Forum di progetto
• Tracciamento del tempo
• Campi personalizzati per problemi, time-entry, progetti e utenti
• Integrazione SCM (SVN, CVS, Git, Mercurial, Bazaar e Darcs)
• Creazione del problema via e-mail
• Supporto per autenticazione LDAP multipla
• Supporto per la registrazione automatica dell'utente
• Supporto multilingue
• Supporto di database multipli

Per le tue esigenze offline, non mi piace l'idea di ingombrare il controllo della versione con i documenti di progettazione. Sono sicuro che hai le tue ragioni per chiederlo, ma davvero quanto spesso sei offline e hai bisogno di accedere ai documenti di progettazione? È probabile che questo sia davvero un caso angolare.

Alcuni wiki (ad es. Ikiwiki ) hanno la capacità di archiviare i propri dati in Git, come hai detto tu. Detto questo, è possibile collegare la documentazione come sottomodulo Git nel proprio repository di origine normale.

Con la configurazione sopra, estrarre la fonte e aggiornare i sottomoduli estrarrebbe l'ultima copia della documentazione. Offline, puoi modificarli a piacimento. Quando torni a una rete, entrambi possono essere riportati in qualsiasi posizione condivisa che stai utilizzando.

La parte imbarazzante di questo è che ogni volta che la documentazione viene aggiornata (anche attraverso l'interfaccia web di Ikiwiki), dovresti anche aggiornare il sottomodulo corrispondente nel repository dei sorgenti di Git. Tuttavia, questo potrebbe essere facilmente automatizzato.

Ha senso archiviare la documentazione nello stesso repository del codice sorgente. La Sfinge mi sembra una buona opzione.

• richiede i file reStructuredText come input, che è facile da modificare e diff
• genera output con collegamento ipertestuale (HTML, PDF, ...)
• puoi fare riferimento al tuo codice sorgente (Python, C, C ++, JavaScript)

Trac fornisce un'interfaccia a Subversion, un Wiki integrato e comode funzionalità di reporting. http://trac.edgewall.org/
Ma non conosco lo stack installato.

Non proverei a conformarmi al lavoro offline. Vorrei utilizzare la risorsa che rende più facile lavorare con tutti. Ad esempio, se stai scrivendo codice PHP, suggerirei di utilizzare la documentazione in linea che può essere generata da PHPDocumentor . Può essere generato ovunque e c'è un plugin per Trac . Quindi online o offline, hai accesso alla documentazione, anche abbastanza rapidamente.

La chiave riguarda l'usabilità. Se è difficile da mantenere, inizierà a soffrire. Quando inizia a soffrire, la qualità della documentazione diminuisce. Quando ciò accade, le persone iniziano a lamentarsi e poi tutto va in discesa.

Usare un wiki per archiviare la documentazione ha molto senso per me.

Veracity è un esempio di DVCS che consente una più stretta integrazione di contenuti wiki e codice sorgente.