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

Is WIKI really appropriate to store document for software development?

Invece di scrivere documenti, pdf e altri tipi di file, perché non scateni il pieno potenziale della WIKI come strumento di collaborazione? Puoi scrivere i tuoi documenti lì, allegare i tuoi diagrammi e anche meglio: se utilizzi Fitnesse , puoi trasformare le tue pagine wiki in documentazione davvero utile e vivente, in quanto può diventare una specifica eseguibile.

Everybody knows that, well-documented software development leads to success

Fai attenzione a questo. I documenti non porteranno al successo, in quanto non trasformeranno il codice crap in uno buono. Ma i documenti sono una parte del modo per il software di successo. Ma solo una parte e non sostituiranno le buone pratiche e le brave persone.

Poiché più risposte puntano a Trac come suggerimento, vorrei suggerire un'alternativa simile, ma a mio parere alternativa: Redmine .

Redmine è una soluzione per la gestione dei progetti, tra cui Wiki, Document Repository e integrazione del controllo della versione. È anche scritto in Ruby on Rails e molto più semplice da estendere e modificare di Trac, nella mia esperienza.

Più di tutto è davvero facile da usare ed è facile far sì che il team lo usi.

Caratteristiche:

• Supporto per più progetti
• Controllo dell'accesso flessibile basato sui ruoli
• Sistema di tracciamento dei problemi flessibile
• Diagramma di Gantt e calendario
• Notizie, documenti e amp; gestione dei file
• Feed & notifiche email
• Per wiki del progetto
• Per i forum di progetto
• Monitoraggio del tempo
• Campi personalizzati per problemi, time-entry, progetti e utenti
• Integrazione SCM (SVN, CVS, Git, Mercurial, Bazaar e Darcs)
• Creazione del problema tramite e-mail
• Supporto dell'autenticazione LDAP multipla
• Supporto per la registrazione automatica dell'utente
• Supporto multilingua
• Supporto per più database

Per le tue esigenze offline, non mi piace l'idea di un controllo della versione ingombrante con i documenti di progettazione. Sono certo che hai i tuoi motivi per chiederlo, ma quanto spesso sei offline e hai bisogno di accedere ai documenti di progettazione? È probabile che questo sia davvero un caso d'angolo.

Alcuni wiki (ad es. Ikiwiki ) hanno la possibilità di memorizzare i loro dati in Git, come hai menzionato. Detto questo, puoi collegare la documentazione come sottomodulo Git sotto il tuo normale repository sorgente.

Con la configurazione di cui sopra, tirando la fonte e aggiornando i sottomoduli tirerebbe l'ultima copia della documentazione. Offline, puoi modificarli a piacimento. Quando torni a una rete, entrambi possono essere reindirizzati a qualsiasi posizione condivisa che stai utilizzando.

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

È opportuno archiviare la documentazione nello stesso repository del codice sorgente. Sphinx mi sembra una buona opzione.

• ci vogliono 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 per Subversion, un Wiki integrato e comode funzioni di reporting. link
Ma non so del tuo stack installato.

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

La chiave riguarda l'usabilità. Se è difficile da mantenere, inizierà a soffrire. Quando inizia a soffrire, la qualità della documentazione diminuisce. Quando ciò accade, la gente inizia 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.