Software para organizar e manter a documentação do projeto, especificação? [fechadas]

15

Estou procurando software para organizar e manter projetos de documentação interna, especificação, requisitos, etc. Atualmente, armazenamos toda a documentação como muitos arquivos MS Word DOC em um repositório de controle de origem, o que nos dá controle de versão, e isso é bom . Mas você não pode pesquisar essas informações, criar links entre elas, categorizar, colaborar.

Requisitos, preferências:

  • Zero instalar no lado do cliente (baseado na WEB).
  • Controle de versão do documento.
  • Anotações do documento.
  • Vinculação de documentos.
  • Pesquisa completa (toda a documentação).
  • MS Word (* .doc) import \ export.
  • editor de texto WYSIWYG.

Sistemas que descobri e experimentei até agora:

por Alex Burtsev 27.12.2011 / 21:19
fonte

6 respostas

6

Que tal algo como Esfinge ?

Você escreve sua documentação em reStructuredText (a sintaxe é semelhante a Markdown, que o Stack Overflow usa) em arquivos de texto simples (= controle de versão fácil) e o Sphinx cria páginas HTML.

Os dois usuários mais proeminentes da Sphinx (que eu conheço) são a linguagem Python e TortoiseHG (veja os links para a documentação gerada pelo Sphinx).

EDITAR:

Acabei de ler que você está falando sobre a documentação interna do projeto, não sobre a documentação do usuário final.
Na minha opinião, algo como o Sphinx é a melhor forma de documentação interna (desde que você possa fazer seus analistas escreverem reStructuredText) porque:

  1. Você pode controlar facilmente os documentos (e as diferenças de arquivos de texto ocupam muito menos espaço do que arquivos binários como .doc ou .pdf).
  2. Se um desenvolvedor quiser um arquivo .doc ou .pdf legível, ele poderá criá-lo com o Sphinx a partir das origens.

Se o Sphinx é muito complicado, existe uma maneira ainda mais fácil: você pode escrever sua documentação no Markdown e usar o Pandoc para criar ( por exemplo) arquivos .rtf, .doc ou .pdf (ele pode fazer muito mais).
Eu achei o Pandoc mais fácil de começar do que o Sphinx, mas o Pandoc não pode criar hierarquias de menu como o Sphinx (como na documentação do Python e TortoiseHG que eu fiz o link acima).

Não importa qual das ferramentas você usa, se você tem um servidor web interno e um servidor de compilação, você pode configurá-lo para que o servidor de compilação gere uma saída HTML e copie isso no servidor web cada vez que alguém enviar algo para a documentação. Então, seus analistas nem precisam pensar no resultado final, eles só precisam se comprometer e empurrar suas mudanças.

    
por 27.12.2011 / 21:42
fonte
5

Bem, você pode tentar implementar um Wiki. O Mediawiki tem todos os recursos que você está falando (funções de busca, histórico de versões, links, categorização). Você terá que certificar-se de saber exatamente qual versão da documentação pertence a qual versão do software, mas isso pode ser feito por convenção de incluir uma referência de versão ou uma categoria específica em cada artigo dependente de versão.

MAS: Você escreve você tem "analistas" que não são desenvolvedores (eu admito, eu não sou fã dessa constelação). Geralmente, esse tipo de pessoa não fica feliz quando você substitui as ferramentas do MS Office por alguma ferramenta de orientação textual como um Wiki. E como o MS-Word não é software livre, acho que o requisito "software livre" não é realmente obrigatório. Nessa situação, um servidor Sharepoint pode ser a melhor alternativa. Não é gratuito, mas o AFAIK tem todos os recursos que você está solicitando, e os documentos ainda podem ser criados usando o Word, o Excel, etc.

    
por 27.12.2011 / 22:48
fonte
2

É sempre melhor manter a especificação e a documentação sob controle de versão, já que isso lhe daria a maior alavancagem, embora a curva de aprendizado fosse um pouco íngreme. No caso de um mecanismo de conhecimento, recomendo o seguinte

  1. Trac - Fácil de usar o sistema de rastreamento de bugs e o mecanismo de conhecimento. Escrito em Python e extensível, você estaria pronto em poucos minutos
  2. MoinMoin - Mecanismo de wiki completo. Novamente Python com muitos recursos

Ambos têm interfaces mínimas, suportam a maioria das estruturas wiki, são fáceis de implementar e de implementar, suportam revisões, possuem um bom editor WYSIWYG e você também pode manter sua documentação e especificação. A menos que seus projetos sejam realmente grandes, você pode escolher qualquer um dos itens acima.

    
por 16.01.2012 / 09:14
fonte
2

Recentemente, começamos a usar o Alfresco DMS, que tem muitas propriedades interessantes:

  • Instalação muito simples
  • Possui um indexador integrado para pesquisa rápida em vários documentos
  • Permite fluxos de trabalho, grupos e, se necessário, acesso específico a documentos pelos clientes
  • Código-fonte aberto
  • Comunidade ativa
  • Integração LDAP / AD / SSO
  • Lida com muitos documentos diferentes

Existem também algumas desvantagens:

  • A interface do usuário nem sempre é intuitiva
  • Não é realmente um wiki, então o trabalho colaborativo simultâneo em um documento pode ser um pouco frágil

Se você decidir dar um giro, entre em contato comigo com suas opiniões.

    
por 09.02.2012 / 11:44
fonte
0

Outra possibilidade pode ser usar LaTeX ou algum outro formater de texto (talvez texinfo ou mesmo lout ) para documentação. Partes dele podem ser geradas por máquina. Existem algumas ferramentas para conversão de HTML, como HeVeA para converter LaTeX em HTML. Você também pode usar o doxygen para gerar documentação a partir de comentários estruturados dentro do seu código-fonte. E as partes escritas à mão da documentação podem (e devem) ser gerenciadas como código-fonte (por exemplo, controle de versão e compilação).

    
por 27.12.2011 / 22:10
fonte
-2

Eu sugeriria usar uma ferramenta UML e ERD, além de seus documentos. Além disso, você pode armazenar esses documentos no ZOHO em ZOHO-Docs , que não é gratuito, mas é extremamente barato e permite instalações de pesquisa de documentos.

Qualquer que seja a ferramenta que você usa, você precisa organizar o conteúdo do documento com cuidado para poder usar a pesquisa de texto e obter resultados significativos. A organização do conteúdo do documento, juntamente com a nomeação de arquivos inteligente e padrão, pode ajudar bastante.

    
por 27.12.2011 / 21:46
fonte