Os wikis são realmente apropriados para armazenar documentos para desenvolvimento de software? [fechadas]

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.

A WIKI é realmente apropriada para armazenar documentos para desenvolvimento de software?

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.

Todo mundo sabe que, o desenvolvimento de software bem documentado leva ao sucesso

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.

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:

• Suporte a múltiplos projetos
• Controle de acesso flexível baseado em função
• Sistema flexível de rastreamento de problemas
• Gráfico e calendário de Gantt
• Gerenciamento de notícias, documentos e arquivos
• Feeds e notificações por email
• Por wiki do projeto
• Por fóruns do projeto
• Rastreamento de tempo
• Campos personalizados para problemas, entradas de tempo, projetos e usuários
• Integração SCM (SVN, CVS, Git, Mercurial, Bazaar e Darcs)
• Criação de problemas por email
• Suporte para autenticação LDAP múltipla
• Suporte de auto-registro do usuário
• Suporte multilíngue
• Suporte a vários bancos de dados

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.

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.

Faz sentido armazenar a documentação no mesmo repositório que o código-fonte. Esfinge parece ser uma boa opção para mim.

• são necessários arquivos reStructuredText como entrada, o que é fácil de editar e diferenciar
• gera saída com hiperlink (HTML, PDF, ...)
• você pode fazer referência ao seu código-fonte (Python, C, C ++, JavaScript)

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.

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.

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.