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

18

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.

Edison Chuang
fonte
3
FYI: Wiki não é um acrônimo, é uma palavra havaiana que significa "rápido".
Jörg W Mittag
O fato de a documentação envolver binários não é realmente um bom motivo para evitar armazená-la no seu sistema de controle de versão. VCSs podem lidar facilmente com arquivos binários. E se você armazená-lo no VCS do seu projeto, você tem a vantagem de poder ramificar sua documentação quando ramifica seu projeto.
JW01
Quanto ao trabalho offline: a solução de força bruta é apenas baixar as páginas que você deseja usando algum leitor offline. Mais elegante é, de alguma forma, clonar todo o wiki, se for prático (por exemplo, copie o banco de dados subjacente e tenha sua própria instalação do wiki). Os wikis baseados em VCS são uma solução ainda mais elegante. Costumo trabalhar offline, e geralmente basta baixar as páginas de que preciso regularmente.
22413 sleske

Respostas:

16

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.

Fernando
fonte
8

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.

Vitor Py
fonte
+1 Eu uso o Redmine no trabalho e é realmente um ótimo sistema.
Luiz Damim
5

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.

Greg Hewgill
fonte
Interessante. Existe uma diferença entre colocar o documento no repositório git e armazená-lo via ikiwiki?
Edison Chuang
1
@ Edison Chuang: Não, não há. De fato, dado um clone de um repositório do ikiwiki, você pode editar as páginas usando o editor de texto de sua escolha (não é necessário usar uma caixa de entrada de texto ruim baseada no navegador). Você pode até ter diferentes ramos do wiki, para manter um instantâneo da documentação mais antiga ou qualquer outra coisa.
Greg Hewgill
Parece que o documento pode ser armazenado no sistema de controle de versão sem problemas, mesmo com os arquivos binários. O desenvolvedor pode apenas usar ferramentas como o ikiwiki para converter páginas wiki em páginas HTML sob demanda.
Edison Chuang
+1 para o mecanismo wiki do Ikiwiki; o mecanismo wiki do Hatta é uma ideia semelhante para os repositórios do Mercurial.
David Cary
O ISTR Fitnesse também armazena suas páginas wiki como arquivos de texto, para que elas também possam ser mantidas no seu sistema de controle de versão, se desejar. Embora seu objetivo principal seja o teste, não há razão para não usá-lo como um sistema wiki de uso geral também para sua documentação.
Jules
4

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

Brecht Machiels
fonte
2

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.

Quíron
fonte
E uma ótima interface para o Mercurial. E é eminentemente hackável.
Frank Shearar
0

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.

Chuck Burgess
fonte
-1

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.

Jace Browning
fonte