Git doit-il être utilisé pour la documentation et la gestion de projet? Le code doit-il être dans un référentiel séparé?

Je démarre un référentiel Git pour un projet de groupe. Est-il judicieux de stocker des documents dans le même référentiel Git en tant que code - il semble que cela soit en conflit avec la nature du flux de révision de Git .

Voici un résumé de ma (mes) question (s):

• Le style de révision Git va-t-il créer de la confusion si le code et les documents sont archivés dans le même référentiel ? Des expériences avec ça?

• Git convient-il au contrôle de révision de la documentation?

• Je ne demande pas si un système de contrôle de révision en général devrait ou ne devrait pas être utilisé pour la documentation - il le devrait.

Merci pour les commentaires jusqu'à présent!

Nous stockons la documentation dans SVN tout le temps. En fait, tout notre manuel d’utilisation est écrit en LaTeX et stocké en SVN. Nous avons choisi LaTeX spécifiquement parce que c'est un langage textuel, et qu'il est facile d'afficher des différences ligne par ligne.

Nous stockons également certains fichiers non au format texte, tels que les fichiers .doc, tableurs, fichiers .zip, etc., de Microsoft Office, mais certains avantages d’un RCS sont perdus lorsque vous ne pouvez pas voir la valeur incrémentielle. diffs.

La clé est vraiment de vous assurer que votre documentation est bien organisée, afin que les gens puissent trouver (et mettre à jour) la documentation (et la source) quand ils en ont besoin.

Cela dépend de quel format utilisez-vous pour la documentation. Si c'est quelque chose à base de texte c'est tout bon.

Git peut également stocker du contenu binaire et vous pouvez suivre les révisions, mais la sortie de diff n'aura aucun sens.

Il est également possible de stocker la documentation dans le code lui-même, comme perldoc pod. Java a également un format / annotation pour cela.

Je ne peux pas imaginer pourquoi vous pensez qu'il pourrait y avoir un problème d'utilisation de git, ou de tout autre système de contrôle de version, pour la documentation. Tout comme le code source, la documentation devrait avoir un historique complet et la possibilité de revenir à une version antérieure si cela devenait nécessaire. Un système de contrôle de version est parfait pour cela.

Il est clair que l'utilisation d'un système de contrôle de version pour stocker des documents n'est pas un enthousiasme. La partie la plus intéressante de la question est de savoir s'il est judicieux de stocker des documents à l'emplacement SAME en tant que code source? Le problème possible ici est qu'il peut être difficile de définir des privilèges d'accès différents pour le code et la documentation dans ce cas. Et dans de nombreux cas, les utilisateurs auront besoin d'accéder à la documentation mais pas au code source, comme le marketing ou les départements de BA.

Dans l'entreprise avec laquelle je travaille, nous mettons la documentation dans SVN. Cependant, après quelques conflits et la nécessité de le partager, nous avons décidé de le transférer vers Mediawiki.

Au début, c’était trac, après cela déplacé vers Mediawiki car il était plus facile à utiliser ...

Le principal problème de SVN était le partage parce que nous avions un système d'autorisation pour SVN.

• Avoir plus que du code source dans un référentiel est une très bonne chose.

  Il regroupe toutes vos ressources et transforme le projet en une entité cohérente et centralisée plutôt qu'en une collection dispersée de fichiers. Les collaborateurs / employés savent où trouver tout, plutôt que d'envoyer "Où puis-je modifier la documentation de la fonctionnalité x?" courriels.

  Vous voudrez garder les choses organisées. Avoir un système pour séparer srcle imagesde le docs. Vous pouvez toujours ajouter un .gitignoreà un répertoire pour garder le référentiel et l'historique propres. Comme les commits Git sont basés sur des fichiers *, vous pouvez découpler les modifications de la source de celles de la documentation aussi fortement que vous le souhaitez.

• Comme d'autres l'ont déjà dit, Git est idéal pour la gestion de versions de documentation, à condition qu'il soit basé sur du texte.

• Je suis complètement d'accord; la documentation doit être versée juste à côté du code.

Ma crédibilité vient d’être un utilisateur de GitHub, de contribuer à un projet et d’en explorer de nombreux autres. D'après mon expérience, un projet complet et unifié est facile à distinguer d'un projet à moitié manquant. J'essaie de contenir tous mes projets dans des répertoires uniques autant que possible.

Je suis venu ici avec une question similaire. Nous venons d'un environnement SVN, où il est évident de garder tous les documents liés à un projet dans le même référentiel. En raison de la nature de SVN, vous pouvez facilement consulter des parties du référentiel. Ainsi, si vous avez juste besoin du code source (par exemple, un déploiement de site Web), ce n'est pas un problème.

Avec Git, les choses sont différentes. Une extraction se situe toujours au niveau racine. Par conséquent, si vous souhaitez tout placer dans le même référentiel, vous obtiendrez toujours la même structure de répertoires. Une approche que j’ai rencontrée consiste à tout placer dans des branches distinctes, c’est-à-dire que vous avez des branches de code (qui sont généralement vos branches maître, de développement, etc.) et une branche doc, qui possède sa propre structure de répertoires distincte. Je ne suis pas encore sûr que ce soit la meilleure idée, mais c'est une suggestion qui contourne le problème qui, je suppose, est à la base de votre question.

J'utilise un wiki pour les documents internes ... je reçois une révision PLUS un accès important / une édition facile. Lorsque la documentation est désynchronisée, mettez-la à jour immédiatement. Pour la documentation destinée aux utilisateurs finaux, utilisez un outil professionnel tel que Madcap Flare. Ils utilisent un dialecte XML pour partager, composer et transformer la documentation.

Dans le code, les pensées sont généralement séparées ligne par ligne. J'ai tendance à écrire de la documentation avec des lignes souples. Lorsque je valide ces fichiers, les lignes ont un paragraphe entier. Ce n'est pas très utile à lire git diff. C’est le problème que j’essayais de résoudre lorsque j’ai trouvé Google dans cette page. Merci à Arne Hartherz de m'avoir présenté à git diff --word-diff. Vous pourriez aimer git diff --color-wordsencore mieux.