O que é uma boa ferramenta para escrever um manual do usuário (arquivo de ajuda), que se integra com o controle de versão [fechado]

Question

As pessoas que escrevem o manual do usuário não são necessariamente programadores, e eles precisam de um editor visual. Uma questão importante é o formato interno da ferramenta de autoria; deve ser texto legível / html, por isso é fácil de comparar versões de páginas individuais verificado no controle de versão.

Answer 1

Existem outros produtos profissionais que permitem ajuda arquivo escrito e que eles têm apoio de "identificação de contexto", que faz ajuda sensível ao contexto possível. Doc para ajudar e RoboHelp são estes tipo de produtos.

Answer 2

DocBook

_{(fonte: docbook.org )}

Answer 3

Microsoft HTML Help Workshop pode ser usado para criar arquivos de ajuda profissional CHM boa qualidade. Tudo que você precisa é um monte de arquivos HTML. A função "compila" Todas essas e pacotes em um único arquivo de ajuda. Os arquivos HTML podem ser gerados usando o Microsoft Word / Frontpage ou mesmo Dreamweaver. Você pode querer considerar a fonte controlar esses arquivos HTML.

Answer 4

Latex . Lyx fornece WYSIWYM para escrever arquivos de látex.

Answer 5

No meu antigo emprego eles usaram uma ferramenta de software louca chamada alargamento .

Ele parecia funcionar muito bem.

Answer 6

Uma boa combinação que considerar é Subversion, DocBook e publicano.

• O controle de versão = Subversion
• Conteúdo Authoring = DocBook
• Publishing = Publican
• Opcional WYSIWYG = Serna

No momento, este é um dos toolchains em uso por maior fornecedor do mundo de soluções de código aberto, e o nome por trás muito do uso mundial de sistemas operacionais baseados em Linux no mercado corporativo. A maioria (e perto de tudo) de documentação oficial da Red Hat é criado de tal maneira a. O mesmo vale para o Fedora.

A principal "pro" aqui é que estes são livremente ferramentas disponíveis, com uma forte sobreposição no mercado de escritores técnicos. Tudo o que será capaz de (mas não pode querer) escrita em XML, e pegando DocBook é como pegar HTML na década de 90. Subversion é uma ferramenta de controle de versão muito comum, que, como DocBook é relativamente fácil de implementar e usar. Publican é uma grande ferramenta de publicação que pode levar DocBook XML, e publicá-lo em PDF, HTML, HTML-single, etc. Obviamente seus escritores pode usar um WYSIWYG como Serna, mas eu usar trechos em Geany (no Fedora) ou TextMate (em OS X) pessoalmente.

A maior "con" é a percepção de tecnicidade. Seus escritores pode querer WYSIWYG (e pode tê-lo), e dependendo de suas necessidades de documentação, este pode ser o que você acaba usando. Como você sabe, há um mercado lá fora, para "Escritores técnicos" que se especializam na fixação estilos Microsoft Word (e de marcação), de modo que os argumentos para a separação de "autoria" de "publicar" são baseados em casos de uso distintos comprovadas, mas para as organizações que exigir documentação a ser realizada até os mesmos padrões de programação de produção fonte de engenharia / /.

Alguns dos conselhos extrema você receberá vem de pessoas e empresas que tenham sido expostos ao valor de documentação XML, e especialmente aqueles nos reinos da DITA, onde certas multinacionais têm uma reputação de aquisições que são influenciados por o formato e disponibilidade do conhecimento do produto. há também os argumentos que o bloqueio a documentação em um formato de "pegajoso" ou fechado não ajuda os requisitos de manutenção futura. Este é o lugar onde as opções de código aberto ganhar apoio em um nível corporativo. Além disso, obviamente, é grátis.

Answer 7

Você pode usar Subversion e MGTEK Ajuda Produtor. Ajuda Produtor faz arquivos de ajuda a partir de documentos do Word. TortoiseSVN vem com scripts para comparar diferentes revisões de documentos do Word, por si só Word (Palavra tem uma ferramenta de comparação de versão).

Os usuários vão querer uma ferramenta de comparação visual que lembra o que eles estão editando. Se eles são apenas ligeiramente não-técnico, DocBook ou Latex não está indo para o trabalho (eu tentei dar meus usuários ambos, e eu até tentei editor do épico como um editor de DocBook que é muito caro, mas não funcionou muito bem depois de tudo). Aderindo a algo que eles sabem (Word) irá evitar muitas dores de cabeça.

Eu estava muito relutante em ir por esse caminho no início também, porque eu queria uma solução que era mais 'tecnicamente perfeito', mas percebi ao longo do tempo que ter usuários felizes e produtivas era mais importante. Basta dizer que eu sei onde você está vindo, mas tente a rota Palavra - ele funciona muito melhor na prática do que todas as soluções baseadas em texto 'puros' que estão lá fora. Os usuários regulares não gosto edição baseada marcação.

Answer 8

Se você estiver usando Visual Studio, dê uma olhada SandCastle - http://www.codeplex.com / Sandcastle .

Há também um par de ferramentas que ajudam a construir arquivos de castelo de areia, tente procurar "castelo de areia" no CodePlex. Um deles é SandCastle Help File Builder ( http://www.codeplex.com/SHFB ), mas eu nunca usei isso para que eu não sei se os usuários não técnicos vai ser feliz com isso.

Answer 9

Madcap Flare é o melhor em torno ferramenta comercial. Escrito pelos ex-colaboradores de Robodoc

Answer 10

Eu criei um sistema de documentação chamado Mandown ( Markdown / HTML / Javascript / arquivo baseado em documentos relativamente ligadas para a portabilidade), que seria facilmente ir sob controle de versão. A parte editor visual você teria que descobrir separadamente - Eu às vezes uso HTML-Kit que pelo menos tem um recurso de visualização.

Consulte Qual é a melhor maneira de software store documentação?

---

Aqui é outra ferramenta para verificar: Xilize

Answer 11

Estamos usando APT . Ele se integra bem com a CI (artefato de construção padrão) e está mais vivo do que para documento do word instância. Também é possível gerar PDFs e outros formatos quando necessário.