Todo mundo sabe que o desenvolvimento de software bem documentado leva ao sucesso. No entanto, geralmente significa que não apenas o texto sem formatação, mas também o conteúdo binário estarão envolvidos no documento, como um diagrama UML. E ouvi muitas pessoas dizerem isso. O sistema de controle de versão não é o local apropriado para os arquivos binários. Compreendo e concordo totalmente com o problema. Perguntei a vários desenvolvedores experientes qual deveria ser o melhor local para armazenar documentos e a resposta que obtive foi "wiki". O Wiki é bom, mas considerei outro problema em potencial. Como o código-fonte que foi armazenado em um sistema de controle de versão se conecta ao documento relacionado no wiki? Digamos que alguém clone o repositório do git ou mercurial. Como ele / ela pode encontrar o documento facilmente? Ou acabei de perder alguma coisa?
Eu sei que alguns sistemas wiki têm a capacidade de integrar-se com sistemas de controle de origem. Mas minha preocupação não é com a capacidade de integração. Se você clonou o código-fonte de um repositório git e, depois de algum tempo, entra em um trem e deseja continuar trabalhando offline no trem (que é um grande recurso do DVCS). De repente, você percebe que não tem acesso a documentos, pois está trabalhando offline no trem. Por outro lado, se o documento fosse armazenado no repositório git, você teria acesso ao documento com o repositório clonado.
fonte
Respostas:
Em vez de escrever documentos, PDFs e outros tipos de arquivos, por que você não lança todo o potencial da WIKI como ferramenta de colaboração? Você pode escrever seus documentos lá, anexar seus diagramas e ainda melhor: se você usar o Fitnesse , poderá transformar suas páginas wiki em documentação realmente útil e viva, pois elas podem se tornar uma especificação executável.
Fique atento com este. Os documentos não levarão ao sucesso, pois não transformarão o código de porcaria em um bom. Mas os documentos fazem parte do caminho para o software bem-sucedido. Mas apenas uma parte e eles não substituirão boas práticas e boas pessoas.
fonte
Como várias respostas apontam para Trac como uma sugestão, eu gostaria de sugerir uma alternativa semelhante, mas melhor na minha opinião, alternativa: Redmine .
O Redmine é uma solução de gerenciamento de projetos, incluindo Wiki, Repositório de Documentos e integração de controle de versão. Também está escrito em Ruby on Rails e é muito mais fácil estender e hackear do que o Trac, na minha experiência.
Mais do que tudo, é realmente fácil de usar e fácil para a equipe usá-lo.
Recursos:
Para suas necessidades offline, não gosto da idéia de controlar o controle de versão com documentos de design. Tenho certeza de que você tem seus motivos para fazer isso, mas na verdade quantas vezes você está offline e precisa de acesso a documentos de design? Provavelmente, este é realmente um caso de esquina.
fonte
Alguns wikis (por exemplo, Ikiwiki ) têm a capacidade de armazenar seus dados no Git, como você mencionou. Dado isso, você pode vincular a documentação como um sub-módulo Git no seu repositório de origem regular.
Com a configuração acima, extrair a fonte e atualizar os submódulos extrairia a cópia mais recente da documentação. Off-line, você pode editar cada um à vontade. Quando você retorna a uma rede, ambos podem ser enviados de volta para qualquer local compartilhado em uso.
A parte complicada disso é que sempre que a documentação é atualizada (mesmo através da interface da web do Ikiwiki), você também precisa atualizar o submódulo correspondente no repositório de origem Git. No entanto, isso pode ser facilmente automatizado.
fonte
Faz sentido armazenar a documentação no mesmo repositório que o código-fonte. Esfinge parece ser uma boa opção para mim.
fonte
O Trac fornece uma interface para o Subversion, um Wiki integrado e facilidades de relatórios convenientes. http://trac.edgewall.org/
Mas eu não sei sobre sua pilha instalada.
fonte
Eu não tentaria me conformar ao trabalho offline. Eu usaria o recurso que facilita o trabalho para todos. Por exemplo, se você estiver escrevendo código PHP, sugiro o uso de documentação embutida que pode ser gerada pelo PHPDocumentor . Pode ser gerado em qualquer lugar e existe um plugin para o Trac . Depois, on-line ou off-line, você também tem acesso à documentação rapidamente.
A chave é sobre usabilidade. Se for difícil de manter, começará a sofrer. Quando começa a sofrer, a qualidade da documentação diminui. Quando isso acontece, as pessoas começam a reclamar e então tudo desce.
fonte
Usar um wiki para armazenar documentação faz muito sentido para mim.
Veracity é um exemplo de DVCS que permite uma integração mais estreita do conteúdo do wiki e do código-fonte.
fonte