Logiciel pour organiser et maintenir la documentation, les spécifications du projet? [fermé]


15

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:


Quel type de documentation de projet avez-vous (textuel, graphique, diagrammes UML, calendriers, spécifications textuelles, user stories etc.)? Combien de personnes doivent le maintenir? Doit-il être synchronisé avec des versions / révisions spécifiques de votre code source?
Doc Brown

@DocBrown, 95% textuel, 3-5 personnes l'écriront. Je suis synchronisé avec les versions des produits logiciels mais pas avec les révisions du code source.
Alex Burtsev

XWiki ressemble à une belle solution, c'est gratuit, il s'intègre bien avec MS Office.
Alex Burtsev

1
Ceci est très proche d'être un doublon de Quel programme utilisez-vous pour écrire de la documentation technique? et la plupart des réponses sont similaires, mais il y a de meilleurs arguments contre l'utilisation d'un wiki pour une telle documentation.
Mark Booth

Que diriez-vous d'un logiciel de gestion des connaissances comme PHPKB ? Ce n'est pas gratuit mais cela semble très bien servir votre objectif.
Anirudh Srivastava

Réponses:


6

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:

  1. Vous pouvez facilement contrôler la version des documents (et les différences de fichiers texte prennent beaucoup, beaucoup moins d'espace que les fichiers binaires comme .doc ou .pdf).
  2. Si un développeur veut un joli fichier lisible .doc ou .pdf, il peut le créer avec Sphinx à partir des sources.

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.


On dirait qu'il génère juste du HTML alors je vais devoir le publier sur un serveur web
Alex Burtsev

1
@AlexBurtsev: Si vous voulez que ce soit public, alors oui. D'un autre côté - maintenant vous utilisez des fichiers Word .doc, vous devez donc les mettre également sur un serveur Web si vous souhaitez les rendre publics.
Christian Specht

Je note que Sphinx a un chemin de "sortie au format PDF".
Robert Harvey

@ChristianSpecht, Wiki et Wordpress ont des plugins pour importer des fichiers Word Doc.
Alex Burtsev

@AlexBurtsev: Je ne sais pas si j'ai compris ce que vous voulez faire avec la documentation. Si vous souhaitez le mettre sur le Web, vous avez besoin d'une sorte de serveur Web, que vous utilisiez Sphinx, Wordpress, un téléchargement .doc ou autre chose. Si vous avez besoin de distribuer la documentation avec un logiciel de rétrécissement, vous pouvez utiliser Sphinx pour générer des PDF ou des fichiers d'aide Windows.
Christian Specht

5

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.


1
Nous avons déjà un serveur SharePoint mais les développeurs ne l'aiment pas et ne veulent pas l'utiliser (je suis développeur moi-même). Nous voulons quelque chose où nous pouvons facilement trouver les informations dont nous avons besoin. Informations classées et liées.
Alex Burtsev

@AlexBurtsev: Je n'ai jamais utilisé le serveur Sharepoint moi-même, mais j'avais l'impression que Sharepoint fournissait toutes les fonctionnalités que vous décriviez. Mais si vous préférez un wiki, Mediawiki vous conviendra. Cependant, vous ferez un effort initial pour l'installer, définir un aperçu de la structure et également définir certaines conventions sur la façon de l'utiliser / de ne pas l'utiliser.
Doc Brown

J'essaie actuellement XWiki pour son intégration MS Office
Alex Burtsev

@DocBrown - SharePoint est horrible. Il n'est pas intuitif, un labyrinthe complet d'onglets et de sous-onglets, et ne maintient aucun contrôle de version approprié. Toute personne l'utilisant serait préférable de vider tous ses documents dans un répertoire partagé sur un serveur interne. Un wiki est généralement la voie à suivre pour ce genre de chose.
Polynôme

2

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

  1. Trac - Système de suivi des bogues et moteur de connaissances facile à utiliser. Écrit en Python et extensible, vous seriez opérationnel en quelques minutes
  2. MoinMoin - Moteur wiki à part entière. Encore une fois Python avec beaucoup de fonctionnalités

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.


2

Nous avons récemment commencé à utiliser Alfresco DMS qui possède de nombreuses propriétés intéressantes:

  • Installation très simple
  • Dispose d'un indexeur intégré pour une recherche rapide à travers des tas de documents
  • Permet des workflows, des groupes et si nécessaire, un accès spécifique aux documents par les clients
  • Open source
  • Communauté active
  • Intégration LDAP / AD / SSO
  • Gère de nombreux documents différents

Il existe également certains inconvénients:

  • L'interface utilisateur n'est pas toujours intuitive
  • Ce n'est pas vraiment un wiki, donc le travail collaboratif simultané sur un document peut être un peu fragile

Si vous décidez de lui donner un swing, veuillez me contacter avec vos opinions.


0

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).


Je ne parle pas de la documentation du produit logiciel (aide, manuel). Je parle de spécifications logicielles, d'exigences commerciales.
Alex Burtsev

Vous pouvez écrire des spécifications logicielles ou tout autre document technique dans LaTeX, et dans certains cercles, c'est une pratique courante.
Basile Starynkevitch

2
LaText me rappelle en quelque sorte * NIX, et nos analystes ne gardent jamais un tel système d'exploitation -), ils vivent dans le monde Windows et ne seront pas d'accord sur quelque chose de plus difficile que Word pour la saisie de texte.
Alex Burtsev

-2

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.