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

15

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

Requisitos, preferências:

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

Sistemas que descobri e tentei até agora:

project-management documentation knowledge-management knowledge-base Alex Burtsev
fonte
Que tipo de documentação você possui (textual, gráfica, diagramas UML, cronogramas, especificações textuais, histórias de usuários etc.)? Quantas pessoas precisam mantê-lo? Ele deve estar sincronizado com versões / revisões específicas do seu código-fonte?
Doc Brown
@DocBrown, 95% textual, 3-5 pessoas escreverão. Está sincronizado com as versões dos produtos de software, mas não com as revisões do código-fonte.
Alex Burtsev
O XWiki parece uma boa solução, é gratuito, integra-se perfeitamente ao MS Office.
Alex Burtsev
1
Isso está muito perto de ser uma duplicata de Qual programa você usa para escrever documentação técnica? e muitas das respostas são semelhantes, mas existem argumentos melhores contra o uso de um wiki para essa documentação.
Mark Booth
Que tal um software de gerenciamento de conhecimento como o PHPKB ? Não é gratuito, mas parece servir muito bem ao seu propósito.
Anirudh Srivastava

Respostas:

6

Que tal algo como Sphinx ?

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

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

EDITAR:

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

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

Se o Sphinx for muito complicado, existe ainda uma maneira mais fácil: você pode escrever sua documentação no Markdown e usar o Pandoc para criar (por exemplo) arquivos .rtf, .doc ou .pdf (pode fazer muito mais).
Achei o Pandoc mais fácil de iniciar do que o Sphinx, mas o Pandoc não pode criar hierarquias de menu agradáveis, como o Sphinx (como na documentação do Python e do TortoiseHG que eu vinculei acima).

Independentemente das ferramentas usadas, se você possui um servidor web interno e um servidor de construção, é possível configurá-lo para que o servidor de construção gere saída HTML e a copie no servidor da Web sempre que alguém enviar algo à documentação. Para que seus analistas nem precisem pensar na saída final, eles apenas precisam confirmar e promover suas alterações.

Christian Specht
fonte
Parece que apenas gera HTML, então terei que publicá-lo em um servidor web #
Alex Burtsev 27/12/11
1
@AlexBurtsev: Se você quer que seja público, então sim. Por outro lado - agora você está usando arquivos .doc do Word, portanto, você deve colocá-los em um servidor Web também se quiser publicá-los.
Christian Specht
Observo que o Sphinx possui um caminho "output to PDF".
Robert Harvey
@ChristianSpecht, Wiki e Wordpress possuem plugins para importar arquivos do Word Doc.
Alex Burtsev
@AlexBurtsev: Não sei se entendi o que você quer fazer com a documentação. Se você deseja colocá-lo na web, precisará de algum tipo de servidor, independentemente de usar Sphinx, Wordpress, um download de .doc ou qualquer outra coisa. Se você precisar distribuir a documentação com o software shrink-wrap, poderá usar o Sphinx para gerar PDFs ou arquivos de ajuda do Windows.
Christian Specht
5

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

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

Doc Brown
fonte
1
Já temos um servidor do SharePoint, mas os desenvolvedores não gostam e não querem usá-lo (eu também sou desenvolvedor). Queremos algo em que possamos encontrar facilmente as informações de que precisamos. Informações categorizadas e vinculadas.
Alex Burtsev
@AlexBurtsev: Eu nunca usei o servidor Sharepoint, mas fiquei com a impressão de que o Sharepoint estava fornecendo todos os recursos que você estava descrevendo. Mas se você preferir um Wiki, o Mediawiki será bom para você. No entanto, você fará um esforço inicial para instalá-lo, definirá algumas orientações de estrutura e também definirá algumas convenções de como usar / não usá-lo.
Doc Brown
Atualmente estou tentando sair XWiki para a sua integração MS Office
Alex Burtsev
@DocBrown - o SharePoint é horrível. Não é intuitivo, é um labirinto completo de guias e sub-guias e não mantém nenhum controle de versão adequado. Qualquer pessoa que usasse seria melhor despejar todos os seus documentos em um diretório compartilhado em um servidor interno. Um wiki é geralmente o caminho a seguir para esse tipo de coisa.
Polinomial
2

É sempre melhor manter a especificação e a documentação sob controle de versão, pois isso proporcionaria a maior vantagem, embora a curva de aprendizado fosse um pouco íngreme. No caso de um mecanismo de conhecimento, recomendo o seguinte

  1. Trac - Sistema de rastreamento de erros e mecanismo de conhecimento fáceis de usar. Escrito em Python e extensível, você estará em funcionamento em alguns minutos
  2. MoinMoin - Mecanismo wiki completo. Novamente Python com muitos recursos

Ambos possuem interfaces mínimas, suportam a maioria das estruturas wiki, são fáceis de implantar e manter, 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 uma das opções acima.

Ubermensch
fonte
2

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

  • Instalação muito simples
  • Possui um indexador embutido para pesquisas rápidas em vários documentos
  • Permite fluxos de trabalho, grupos e, se necessário, acesso específico a documentos pelos clientes
  • Código 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 fazer um balanço, entre em contato comigo com suas opiniões.

Dibbeke
fonte
0

Outra possibilidade pode ser usar o LaTeX ou algum outro formatador de texto (talvez texinfo ou mesmo lout ) para documentação. Partes dele podem ser geradas à máquina. Existem algumas ferramentas para conversão de HTML, como o HeVeA para converter o LaTeX em HTML. Você também pode usar 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 construção).

Basile Starynkevitch
fonte
Não estou falando da documentação do produto de software (ajuda, manual). Estou falando de especificação de software, requisitos de negócios.
Alex Burtsev
Você pode escrever especificações de software ou qualquer documento técnico no LaTeX e, em alguns círculos, é prática comum.
Basile Starynkevitch
2
De alguma forma, o LaText me lembra o * NIX, e nossos analistas nunca reúnem esse sistema operacional -), eles vivem no mundo do Windows e não concordam com algo mais difícil do que o Word para entrada de texto.
Alex Burtsev
-2

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

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

NoChance
fonte