Je recherche des logiciels pour organiser et maintenir la documentation interne des projets, les spécifications, les exigences, etc. Actuellement, nous stockons toute la documentation sous forme de nombreux fichiers DOC MS Word dans un référentiel de contrôle de source, ce qui nous donne un contrôle de version, et c'est bien. Mais vous ne pouvez pas rechercher ces informations, créer des liens entre elles, classer, collaborer.
Exigences, préférences:
- Installation zéro côté client (basé sur WEB).
- Contrôle de version de document.
- Annotations de documents.
- Liaison de documents.
- Recherche complète (toute la documentation).
- Importation / exportation MS Word (* .doc).
- Éditeur de texte WYSIWYG.
Systèmes que j'ai découverts et essayés jusqu'à présent:
Réponses:
Que diriez-vous de quelque chose comme Sphinx ?
Vous écrivez votre documentation dans reStructuredText (la syntaxe est similaire à Markdown, que Stack Overflow utilise) dans des fichiers texte (= facile à contrôler la version) et Sphinx crache des pages HTML.
Les deux utilisateurs les plus importants de Sphinx (à ma connaissance) sont le langage Python et TortoiseHG (voir les liens pour la documentation générée par Sphinx).
ÉDITER:
Je viens de lire que vous parlez de documentation interne au projet, pas de documentation pour l'utilisateur final.
À mon avis, quelque chose comme Sphinx est également le meilleur moyen de documentation interne (à condition que vous puissiez demander à vos analystes d'écrire reStructuredText) parce que:
Si Sphinx est trop compliqué, il existe même un moyen plus simple: vous pouvez écrire votre documentation dans Markdown et utiliser Pandoc pour créer (par exemple) des fichiers .rtf, .doc ou .pdf (cela peut faire beaucoup plus).
J'ai trouvé Pandoc plus facile à démarrer que Sphinx, mais Pandoc ne peut pas créer de belles hiérarchies de menus comme Sphinx (comme dans la documentation Python et TortoiseHG que j'ai liée ci-dessus).
Peu importe les outils que vous utilisez, si vous avez un serveur Web interne et un serveur de génération, vous pouvez le configurer de sorte que le serveur de génération génère une sortie HTML et la copie sur le serveur Web chaque fois que quelqu'un envoie quelque chose à la documentation. Ainsi, vos analystes n'ont même pas à penser à la sortie finale, ils ont juste besoin de s'engager et de pousser leurs changements.
la source
Eh bien, vous pouvez essayer d'implémenter un Wiki. Mediawiki possède toutes les fonctionnalités manquantes dont vous parlez (fonctions de recherche, historique des versions, liens, catégorisation). Vous devrez vous assurer de savoir exactement quelle version de la documentation appartient à quelle version du logiciel, mais cela peut être fait par convention en incluant une référence de version ou une catégorie spécifique dans chaque article dépendant de la version.
MAIS: Vous écrivez que vous avez des "analystes" qui ne sont pas des développeurs (j'avoue, je ne suis pas fan de cette constellation). Ce genre de personnes n'est souvent pas satisfait lorsque vous remplacez leurs outils MS Office par un outil orienté texte comme un Wiki. Et comme MS-Word n'est pas un logiciel libre, je suppose donc que l'exigence de "logiciel libre" n'est pas vraiment un must. Dans cette situation, un serveur Sharepoint pourrait être la meilleure alternative. Pas gratuit, mais AFAIK, il possède toutes les fonctionnalités que vous demandez, et les documents peuvent toujours être créés à l'aide de Word, Excel, etc.
la source
Il est toujours préférable de garder les spécifications et la documentation sous contrôle de version car cela vous donnerait le plus grand effet de levier, bien que la courbe d'apprentissage soit un peu raide. Dans le cas d'un moteur de connaissances, je recommande ce qui suit
Les deux ont des interfaces minimales, prennent en charge la plupart des structures wiki, assez faciles à déployer et à entretenir, prennent en charge les révisions, ont un bon éditeur WYSIWYG et vous pouvez même conserver votre documentation et vos spécifications. À moins que vos projets ne soient vraiment énormes, vous pouvez choisir l'une des options ci-dessus.
la source
Nous avons récemment commencé à utiliser Alfresco DMS qui possède de nombreuses propriétés intéressantes:
Il existe également certains inconvénients:
Si vous décidez de lui donner un swing, veuillez me contacter avec vos opinions.
la source
Une autre possibilité pourrait être d'utiliser LaTeX ou un autre formateur de texte (peut-être texinfo ou même lout ) pour la documentation. Certaines parties peuvent être générées par machine. Il existe quelques outils pour la conversion HTML, comme HeVeA pour convertir LaTeX en HTML. Vous pouvez également utiliser doxygen pour générer de la documentation à partir de commentaires structurés à l'intérieur de votre code source. Et les parties manuscrites de la documentation peuvent (et doivent) être gérées comme du code source (contrôle de version egwrt et build).
la source
Je suggérerais d'utiliser un outil UML et ERD, en plus de vos documents. Vous pouvez également stocker ces documents sur ZOHO à l'adresse ZOHO-Docs , ce qui n'est pas gratuit, mais il est extrêmement bon marché et permet des fonctions de recherche de documents.
Quel que soit l'outil que vous utilisez, vous devez organiser soigneusement le contenu du document pour pouvoir utiliser la recherche de texte et obtenir des résultats significatifs. L'organisation du contenu des documents associée à une dénomination intelligente et standard des fichiers pourrait grandement aider.
la source