Les wikis sont-ils vraiment appropriés pour stocker des documents pour le développement de logiciels? [fermé]


18

Tout le monde sait qu'un développement logiciel bien documenté mène au succès. Cependant, cela signifie généralement que non seulement du texte brut mais aussi du contenu binaire seront impliqués dans le document, comme un diagramme UML. Et j'ai entendu beaucoup de gens dire cela. Le système de contrôle de version n'est pas l'endroit approprié pour les fichiers binaires. Je comprends parfaitement et suis d'accord avec le problème. J'ai demandé à plusieurs développeurs chevronnés où le meilleur endroit pour stocker des documents devrait être et la réponse que j'ai obtenue était "wiki". Le wiki est bon mais j'ai considéré un autre problème potentiel. Comment le code source qui a été stocké dans un système de contrôle de version peut-il se connecter à son document associé dans le wiki? Disons que quelqu'un clone le référentiel de git ou mercurial. Comment trouver facilement le document? Ou ai-je juste raté quelque chose?

Je sais que certains systèmes wiki ont la capacité de s'intégrer aux systèmes de contrôle de source. Mais ma préoccupation ne concerne pas la capacité d'intégration. Si vous avez cloné le code source d'un référentiel git et après un certain temps, vous montez dans un train et souhaitez continuer à travailler hors ligne sur le train (ce qui est une grande caractéristique de DVCS). Ensuite, vous réalisez soudainement que vous n'avez aucun accès au document puisque vous travaillez hors ligne dans le train. En revanche, si le document était stocké dans le référentiel git, vous auriez accès au document avec le référentiel cloné.


3
FYI: Wiki n'est pas un acronyme, c'est un mot hawaïen qui signifie "rapide".
Jörg W Mittag

Le fait que la documentation implique des binaires n'est pas vraiment une bonne raison pour éviter de la stocker dans votre système de contrôle de version. Les VCS peuvent facilement gérer des fichiers binaires. Et si vous le stockez dans le VCS de votre projet, vous avez l'avantage de pouvoir brancher votre documentation lorsque vous branchez votre projet.
JW01

En ce qui concerne le travail hors ligne: La solution de force brute consiste à télécharger simplement les pages que vous souhaitez en utilisant un lecteur hors ligne. Il est plus élégant de cloner le wiki dans son ensemble, si cela est possible (par exemple, copier la base de données sous-jacente et avoir votre propre installation du wiki). Les wikis basés sur VCS sont une solution encore plus élégante. Je travaille souvent hors ligne et, généralement, il suffit de télécharger régulièrement les pages dont j'ai besoin.
sleske

Réponses:


16

WIKI est-il vraiment approprié pour stocker des documents pour le développement logiciel?

Au lieu d'écrire des documents, des fichiers PDF et d'autres types de fichiers, pourquoi ne pas libérer le plein potentiel du WIKI en tant qu'outil de collaboration? Vous pouvez y écrire vos documents, y attacher vos diagrammes et encore mieux: si vous utilisez Fitnesse , vous pouvez transformer vos pages wiki en documentation vraiment utile et vivante, car elles peuvent devenir une spécification exécutable.

Tout le monde sait que le développement de logiciels bien documentés mène au succès

Attention à celui-ci. Les documents NE CONDUIRONT PAS AU SUCCÈS, car ils ne transformeront pas le code de la merde en bon. Mais les documents sont une partie du chemin vers le logiciel réussi. Mais juste une partie et ils ne remplaceront pas les bonnes pratiques et les bonnes personnes.


8

Étant donné que plusieurs réponses indiquent Trac comme une suggestion, j'aimerais suggérer une alternative similaire, mais meilleure à mon avis: Redmine .

Redmine est une solution de gestion de projet, comprenant l'intégration du wiki, du référentiel de documents et du contrôle de version. Il est également écrit en Ruby on Rails et beaucoup plus facile à étendre et à pirater que Trac, selon mon expérience.

Plus que tout, il est vraiment facile à utiliser et il est facile de faire en sorte que l'équipe l'utilise.

Fonctionnalités:

  • Prise en charge de plusieurs projets
  • Contrôle d'accès flexible basé sur les rôles
  • Système de suivi des problèmes flexible
  • Diagramme de Gantt et calendrier
  • Gestion des actualités, des documents et des fichiers
  • Flux et notifications par e-mail
  • Wiki par projet
  • Forums par projet
  • Suivi du temps
  • Champs personnalisés pour les problèmes, les entrées de temps, les projets et les utilisateurs
  • Intégration SCM (SVN, CVS, Git, Mercurial, Bazaar et Darcs)
  • Création d'un problème par e-mail
  • Prise en charge de plusieurs authentifications LDAP
  • Prise en charge de l'auto-inscription des utilisateurs
  • Prise en charge multilingue
  • Prise en charge de plusieurs bases de données

Pour vos besoins hors ligne, je n'aime pas l'idée d'encombrer le contrôle de version avec des documents de conception. Je suis sûr que vous avez vos raisons de le demander, mais à quelle fréquence êtes-vous hors ligne et avez-vous besoin d'accéder aux documents de conception? Il y a de fortes chances que ce soit un cas d'angle.


+1 J'utilise Redmine au travail et c'est vraiment un excellent système.
Luiz Damim

5

Certains wikis (par exemple Ikiwiki ) ont la possibilité de stocker leurs données dans Git, comme vous l'avez mentionné. Cela dit, vous pouvez lier la documentation en tant que sous-module Git sous votre référentiel source habituel.

Avec la configuration ci-dessus, extraire la source et mettre à jour les sous-modules extraira la dernière copie de la documentation. Hors ligne, vous pouvez modifier chacun à volonté. Lorsque vous revenez à un réseau, les deux peuvent être repoussés vers l'emplacement partagé que vous utilisez.

La partie gênante de cela est que chaque fois que la documentation est mise à jour (même via l'interface web Ikiwiki), vous devrez également mettre à jour le sous-module correspondant dans le référentiel source Git. Cependant, cela pourrait facilement être automatisé.


Intéressant. Y a-t-il une différence entre mettre le document dans le référentiel git et stocker le document via ikiwiki?
Edison Chuang

1
@Edison Chuang: Non, il n'y en a pas. En fait, étant donné un clone d'un référentiel ikiwiki, vous pouvez modifier les pages en utilisant l'éditeur de texte de votre choix (vous n'avez pas besoin d'utiliser une boîte de saisie de texte basée sur un navigateur pourri). Vous pouvez même avoir différentes branches du wiki, pour garder un instantané de la documentation plus ancienne ou autre.
Greg Hewgill

Il semble que le document puisse être stocké dans le système de contrôle de version sans aucun problème, même si les fichiers binaires. Le développeur peut simplement utiliser des outils comme ikiwiki pour convertir des pages wiki en pages HTML à la demande.
Edison Chuang

+1 pour le moteur wiki Ikiwiki; le moteur wiki Hatta est une idée similaire pour les référentiels Mercurial.
David Cary

ISTR Fitnesse stocke également ses pages wiki sous forme de fichiers texte, afin qu'elles puissent également être conservées dans votre système de contrôle de version si vous le souhaitez. Bien que son objectif principal soit de tester, il n'y a aucune raison de ne pas l'utiliser également comme système wiki à usage général pour votre documentation.
Jules

4

Il est logique de stocker la documentation dans le même référentiel que le code source. Le Sphinx me semble être une bonne option.


2

Trac fournit une interface à Subversion, un Wiki intégré et des fonctionnalités de reporting pratiques. http://trac.edgewall.org/
Mais je ne connais pas votre pile installée.


Et une belle interface avec Mercurial. Et c'est éminemment piratable.
Frank Shearar

0

Je n'essaierais pas de me conformer au travail hors ligne. J'utiliserais la ressource qui facilite son utilisation pour tout le monde. Par exemple, si vous écrivez du code PHP, je suggérerais d'utiliser une documentation en ligne qui peut être générée par PHPDocumentor . Il peut être généré n'importe où et il existe un plugin pour Trac . Ensuite en ligne ou hors ligne, vous avez accès à la documentation, assez rapidement aussi.

La clé est la convivialité. S'il est difficile à entretenir, il commencera à en souffrir. Lorsqu'elle commence à souffrir, la qualité de la documentation diminue. Lorsque cela se produit, les gens commencent à se plaindre, puis tout se dégrade.


-1

Utiliser un wiki pour stocker de la documentation a beaucoup de sens pour moi.

Veracity est un exemple de DVCS qui permet une intégration plus étroite du contenu wiki et du code source.

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.