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é.
la source
Réponses:
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.
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.
la source
É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:
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.
la source
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é.
la source
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.
la source
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.
la source
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.
la source
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.
la source