O Git deve ser usado para documentação e gerenciamento de projetos? O código deve estar em um repositório separado?

Estou iniciando um repositório Git para um projeto de grupo. Faz sentido armazenar documentos no mesmo repositório Git que o código - parece que isso entra em conflito com a natureza do fluxo de revisão do git.

Aqui está um resumo das minhas perguntas:

• O estilo de revisão do Git será confuso se o código e os documentos forem verificados no mesmo repositório ? Experiências com isso?

• O Git é adequado para o controle de revisão de documentação?

• NÃO estou perguntando se um Sistema de Controle de Revisão em geral deve ou não ser usado para documentação - deveria.

Obrigado pelo feedback até agora!

Armazenamos documentação no SVN o tempo todo. De fato, todo o manual do usuário está escrito em LaTeX e armazenado em SVN. Escolhemos o LaTeX especificamente porque é uma linguagem baseada em texto e fácil de mostrar diferenças linha a linha.

Também armazenamos alguns arquivos não formatados em texto, como arquivos .doc do Microsoft Office, planilhas, arquivos .zip, etc., quando necessário ... mas alguns dos benefícios de um RCS são perdidos quando você não consegue ver o valor incremental diffs.

A chave é realmente garantir que sua documentação esteja bem organizada, para que as pessoas possam encontrar (e atualizar) a documentação (e a fonte) quando necessário.

Bem, depende de qual formato você usa para a documentação. Se é algo baseado em texto, é tudo de bom.

O Git também pode armazenar conteúdo binário e você pode acompanhar as revisões, mas a saída do diff não fará sentido.

Também é possível armazenar a documentação no próprio código, como perldoc pod, java também possui algum formato / anotação para isso.

Não consigo imaginar por que você acha que pode haver um problema ao usar o git, ou qualquer outro sistema de controle de versão, para documentação. Assim como o código-fonte, a documentação deve ter um histórico completo e a capacidade de reverter para uma versão anterior, se necessário. Um sistema de controle de versão é perfeito para isso.

É claro que o uso de algum tipo de sistema de controle de versão para armazenar documentos não é fácil. A parte mais interessante da pergunta é se é uma boa ideia armazenar documentos no mesmo local como o código-fonte? O possível problema aqui é que pode ser difícil definir privilégios de acesso diferentes para código e documentação nesse caso. E, em muitos casos comerciais, as pessoas precisarão acessar documentos, mas não o código-fonte, como departamentos de marketing ou BA.

Na empresa em que trabalho, colocamos documentação no SVN. No entanto, após alguns conflitos e a necessidade de compartilhá-lo, decidimos movê-lo para o Mediawiki.

No começo, era trac, depois foi para o Mediawiki, porque era mais fácil de usar ...

O principal problema com o SVN foi a causa do compartilhamento, tínhamos um sistema de autorização para o SVN.

• Ter mais do que apenas código-fonte em um repositório é uma coisa muito boa.

  Ele agrupa todos os seus recursos e transforma o projeto em uma entidade coesa e centralizada, em vez de uma coleção dispersa de arquivos. Os colaboradores / funcionários sabem onde encontrar tudo, em vez de enviar "Onde altero a documentação do recurso x?" e-mails.

  Você vai querer manter as coisas organizadas. Tenha um sistema para separar o srcdo imagesdo docs. Você sempre pode adicionar um .gitignorea um diretório para manter o repositório e o histórico limpos. Como as confirmações do Git são baseadas em arquivos, * você pode separar as alterações de origem das alterações na documentação da maneira que desejar.

• Como outros já disseram, o Git é ótimo para versionamento de documentação, desde que baseado em texto.

• Eu concordo completamente; a documentação deve ser versionada ao lado do código.

Minha credibilidade vem de ser um usuário do GitHub e contribuir para um projeto e explorar muitos outros. Na minha experiência, é fácil distinguir um projeto completo e unificado de um projeto que está faltando pela metade. Tento conter todos os meus projetos em diretórios únicos sempre que possível.

Eu vim aqui com uma pergunta semelhante. Nós viemos de um ambiente SVN, onde basicamente é fácil manter todos os materiais relacionados a um projeto no mesmo repositório. Devido à natureza do SVN, você pode facilmente verificar partes do repositório; portanto, se você precisar apenas do código-fonte (por exemplo, uma implantação de site), não há problema.

Com o Git, as coisas são diferentes. Um checkout está sempre no nível raiz, portanto, se você quiser colocar tudo no mesmo repositório, sempre terá a mesma estrutura de diretórios. Uma abordagem que me deparei é colocar tudo em ramificações separadas, ou seja, você tem ramificações de código (que normalmente seriam suas ramificações normais de mestre, desenvolvimento etc.) e uma ramificação de documentos, que possui sua própria estrutura de diretórios separada. Ainda não tenho certeza de que é a melhor ideia, mas é uma sugestão que contorna o problema que imagino estar na base da sua pergunta.

Eu uso um wiki para documentos internos ... obtenha revisão além do acesso proeminente / edição fácil. Quando a documentação estiver fora de sincronia, atualize-a imediatamente. Para documentação do usuário final, considere uma ferramenta profissional como o Madcap Flare. Eles usam um dialeto XML para compartilhar, compor e transformar a documentação.

No código, os pensamentos são tipicamente separados linha por linha. Costumo escrever documentação com envoltórios de linhas suaves. Quando eu confirmo esses arquivos, as linhas têm um parágrafo inteiro. Isso não é muito útil para ler git diff. Esse é o problema que eu estava tentando resolver quando pesquisei no Google e encontrei esta página. Agradeço a Arne Hartherz por me apresentar git diff --word-diff. Você pode gostar git diff --color-wordsainda melhor.