Software per organizzare e mantenere la documentazione del progetto, le specifiche? [chiuso]

Che ne dici di qualcosa come Sfinge ?

Scrivi la tua documentazione in reStructuredText (la sintassi è simile a Markdown, che Stack Overflow utilizza) in file di testo semplice (= facile controllo della versione) e Sphinx sputa pagine HTML.

I due principali utenti di Sfinge (che io conosca) sono la lingua di Python e TortoiseHG (vedi i collegamenti per la documentazione generata da Sfinge).

Modifica

Ho appena letto che stai parlando di documentazione interna al progetto, non di documentazione per l'utente finale.
Secondo me, qualcosa come la Sfinge è il modo migliore anche per la documentazione interna (a condizione che tu possa convincere i tuoi analisti a scrivere reStructuredText) perché:

1. Puoi facilmente controllare la versione dei documenti (e le differenze tra i file di testo richiedono molto meno spazio rispetto ai file binari come .doc o .pdf).
2. Se uno sviluppatore vuole un file .doc o .pdf leggibile, può crearlo con Sphinx dai sorgenti.

Se la Sfinge è troppo complicata, c'è anche un modo più semplice: puoi scrivere la tua documentazione in Markdown e usare Pandoc per creare ( ad esempio) .rtf, .doc o .pdf (può fare molto di più).
Ho trovato Pandoc più facile da avviare rispetto a Sphinx, ma Pandoc non può creare gerarchie di menu come Sphinx (come nella documentazione di Python e TortoiseHG che ho linkato sopra).

Indipendentemente dagli strumenti utilizzati, se disponi di un server Web interno e di un server di build, puoi configurarlo in modo che il server di generazione generi l'output HTML e copi questo sul server Web ogni volta che qualcuno invia qualcosa a la documentazione. Quindi i tuoi analisti non devono neanche pensare all'output finale, devono solo impegnarsi e spingere i loro cambiamenti.

Bene, puoi provare a implementare un Wiki. Mediawiki ha tutte le funzionalità mancanti di cui stai parlando (funzioni di ricerca, cronologia delle versioni, collegamenti, categorizzazione). Dovrai assicurarti di sapere esattamente quale versione della documentazione appartiene a quale versione del software, ma ciò può essere fatto per convenzione includendo un riferimento alla versione o una categoria specifica in ogni articolo dipendente dalla versione.

MA: scrivi che hai "analisti" che non sono sviluppatori (ammetto, non sono un fan di quella costellazione). Spesso questi tipi di persone non sono felici quando si sostituiscono gli strumenti di MS Office con uno strumento orientato al testo come un Wiki. E dal momento che MS-Word non è software libero, quindi credo che il requisito "software libero" non sia davvero un dovere. In questa situazione, un server Sharepoint potrebbe essere l'alternativa migliore. Non libero, ma AFAIK ha tutte le funzionalità che stai richiedendo, e i documenti possono ancora essere creati usando Word, Excel ecc.

È sempre meglio mantenere le specifiche e la documentazione sotto controllo di versione in quanto ti darebbe la maggiore leva, anche se la curva di apprendimento sarebbe un po 'ripida. In caso di un motore di conoscenza, consiglio quanto segue

1. Trac - Sistema di tracciamento dei bug e motore della conoscenza facili da usare. Scritto in Python ed estensibile, potresti essere attivo e funzionante in pochi minuti
2. MoinMoin - Motore wiki completo a tutti gli effetti. Ancora Python con molte funzionalità

Entrambi hanno interfacce minime, supportano la maggior parte delle strutture wiki, sono abbastanza facili da implementare e gestire, supportano le revisioni, hanno un buon editor WYSIWYG e puoi anche conservare la documentazione e le specifiche. A meno che i tuoi progetti non siano davvero enormi, puoi scegliere uno dei precedenti.

Recentemente abbiamo iniziato a utilizzare il Alfresco DMS che ha molte proprietà interessanti:

• Installazione molto semplice
• Ha un indicizzatore incorporato per la ricerca rapida di un mucchio di documenti
• Consente flussi di lavoro, gruppi e, se necessario, accesso specifico ai documenti da parte dei clienti
• Open-source
• Comunità attiva
• Integrazione LDAP / AD / SSO
• Gestisce molti documenti diversi

Ci sono anche alcuni svantaggi:

• L'interfaccia utente non è sempre intuitiva
• Non è davvero una wiki, quindi il lavoro collaborativo simultaneo su un documento potrebbe essere un po 'fragile

Se decidi di dargli un tocco, per favore contattami con le tue opinioni.

Un'altra possibilità potrebbe essere l'uso di LaTeX o di qualche altro formattatore di testo (forse texinfo o anche lout ) per la documentazione. Parti di esso possono essere generate dalla macchina. Ci sono alcuni strumenti per la conversione HTML, come HeVeA per convertire LaTeX in HTML. Puoi anche utilizzare doxygen per generare documentazione dai commenti strutturati all'interno del codice sorgente. E le parti scritte a mano della documentazione possono (e dovrebbero) essere gestite come codice sorgente (ad esempio controllo e build della versione w.r.t.)

Suggerirei di utilizzare uno strumento UML e ERD, oltre ai tuoi documenti. Inoltre, puoi archiviare questi documenti su ZOHO all'indirizzo ZOHO-Docs , che non è gratuito, ma è estremamente economico e consente la ricerca di documenti.

Qualunque sia lo strumento che si utilizza, è necessario organizzare attentamente il contenuto del documento per poter utilizzare la ricerca di testo e ottenere risultati significativi. L'organizzazione dei contenuti dei documenti insieme a una denominazione dei file intelligente e standard può essere di grande aiuto.