Qual é a melhor maneira de armazenar a documentação do software? [fechadas]

Question

Uma resposta óbvia é "um wiki interno". Quais são os prós e contras de uma wiki usado para documentação de software? Qualquer outra sugestão? O que você está usando para a documentação do software?

Loren Segal - Infelizmente não temos suporte para qualquer ferramenta doc a informações de compilação do código-fonte comentários, mas eu concordo que seria a melhor maneira de armazenar documentação técnica. A minha pergunta era sobre todo o tipo de documentação tho - do tipo sysadmin a documentação do usuário.

Answer 1

Essa é uma pergunta muito aberta, e depende de muitos fatores.

De um modo geral, se você usar uma linguagem que tem boas ferramentas de geração de documentação (javadoc, doxygen, MS C # stuff), você deve escrever sua documentação acima de seus métodos e ter suas ferramentas de gerar as páginas. A vantagem é que você mantenha o source do seu texto ao lado de seu código que significa que é orgnanized no lugar logicamente correta e facilmente editável quando você faz uma alteração no comportamento do método.

Se você não tem um bom suporte ferramenta doc ou não tem acesso ao código fonte, de Wiki não são uma má idéia, mas eles são uma segunda escolha para o acima.

Nota: Eu estou falando apenas cerca de documentação de código aqui. Outros artefatos, obviamente, não podem ser armazenados ao lado code-- um wiki é um ótimo lugar para colocar esses documentos. Alternativamente, se você usar algum CMS você pode simplesmente cometê-los em alguma pasta docs/ como texto / pdf / whatever arquivos a serem editáveis ??através do repositório. A vantagem não é que eles ficam com o repositório se ele for movido enquanto que um wiki não (necessariamente).

Answer 2

Ferramentas são importantes, mas não fique muito atolados em encontrar a ferramenta mágica. Nenhuma ferramenta que eu encontrei ainda tem um "tudo o documento magicamente usando minúsculos duendes invisíveis" tickbox. : -)

Um wiki irá funcionar bem. Ou Sharepoint. docs ou Google. Ou você pode usar um repositório SVN. Inferno você poderia fazê-lo com canetas, papel de carta, e um armários de arquivo se você realmente tinha que fazer. (Eu realmente não recomendo isso!)

A chave importante grande é que você precisa ter buy-in em toda a organização. O que acontece em um monte de lojas é que eles ir e gastar um monte de tempo e dinheiro em alguma solução fantasia como Sharepoint, e depois todo mundo usa-lo religiosamente por cerca de duas semanas, e então as pessoas ficam ocupados com bater o mais recente marco e essa é a última alguém ouvir sobre isso.

Dependendo da sua organização, campo, o tipo de produtos o seu desenvolvimento, etc., existem algumas soluções para isso, mas de uma forma ou de outra você precisa configurar um sistema e uso que . Nomear alguém o czar documentação oficial, dar-lhes uma cluebat, e dizer-lhes para atingir as pessoas na toda cabeça dizem "oh sim, eu vou terminar documentar que na próxima semana ...". se é isso que é preciso. : -)

Como para obter ferramentas ... Eu recomendo Confluence por Atlassian. É uma multa wiki, ele é projetado para trabalhar em um ambiente corporativo, tem um monte de características interessantes, é customizável, integra-se bem com algumas das outras ferramentas bacanas da Atlassian, e é basicamente um produto sólido bonito.

Answer 3

«documentação Software» é um termo muito geral. Há «End documentação do usuário», «documentação desenvolvedor», «QA Documentação». Primeiro é normalmente desenvolvido por techwriters qualificados. Outras podem ser formados dinamicamente a partir de wikis, comentários de documentação de código fonte etc. Todo este processo de manutenção material geralmente é muito complexo e cada empresa de software seguir o seu próprio caminho. Mas há um ponto necessário para todas essas formas: cada commiter código, arquiteto, gerente, coordenador do QA deve armazenar bem arranjado cada pedaço de informação que pode ser útil para os outros. E alguém deve manter um olho sobre este armazenamento de peças e pedaços Reorganizar se necessário. Todos esses passos muito melhorar todas as atividades relacionadas ao processo de desenvolvimento.

Answer 4

Assumindo que você está falando de documentação de código contra a documentação do usuário, um wiki interno é ótimo se você não precisa distribuir a documentação para o exterior código da sua organização, para contratados ou parceiros.

Javadoc ou Doxygen é mais adequado se desejar documentação de código distribuível.

Se você está se referindo a documentação do usuário, você pode querer ter um olhar para DITA .

Answer 5

Eu comecei a experimentar com uma maneira de fazer a documentação do usuário com esses objetivos:

Markdown / HTML / Javascript /-file com base documentos relativamente ligadas para a portabilidade ( pode ser executado no sistema de arquivos local ou você pode jogá-lo em um servidor web ), incorporado na manipulação de imagens ( interativamente redimensionamento ), e de código aberto no caso de alguém pode querer fazer alguma coisa com a coisa louca.

A sua fonte documento está escrito em Markdown e renderizados para HTML via JavaScript em tempo de execução do navegador.

Mandown - http://wittman.org/mandown/

Answer 6

Atualmente usamos documentação em linha analisada por um aplicativo externo (PHP + PhpDocumenter) mais diversos wikis internos. Às vezes é doloroso na melhor das hipóteses (principalmente porque apenas uma atualização pessoa os wikis ou os docs ...)

No entanto, eu estive olhando usando ikiwiki fazer docs internos. Ele se integrar com o sistema countrol origem (incluindo Git, Subversion, Mercurial, Bazaar, TLA e Monocromático) para que todos os seus documentos pista com o seu projeto. Ele é construído em Perl e tem um extenso sistema de encaixe (incluindo várias linguagens de marcação, sendo o padrão Markdown). Além disso, o sistema de controle de origem é plug-in baseado, por isso, se o que você usa não é imediatamente apoiado você pode adicionar seu próprio país. Em seu idioma preferido, se necessário, uma vez que suporta plugins não-perl, também.

Answer 7

Minha empresa usa uma variedade de Sharepoint e uma wiki. Sharepoint para documentos específicos como requerimentos, apresentações, contratos, etc, enquanto o wiki é usado como uma ajuda guiar um repositório de desenvolvedor para tutoriais sobre o uso de bibliotecas desenvolvidas internamente.

Answer 8

Sim, nós usamos um wiki, também usamos documentos do Google. Eu acho que os documentos do Google é melhor do que a maioria dos wikis eu tentei e, se você não precisa acompanhar todas as mudanças, você não perde nada. Google docs fornece uma boa estrutura de colaboração.