Precisa de aconselhamento - Desenvolvendo um sistema de documentação flexível, fortemente focado na localização [fechado]

Question

Fui encarregado de construir um sistema/plataforma de documentação.

Aqui está uma pequena lista dos principais requisitos:

• Facilmente localizado:Isso precisará oferecer suporte a cerca de uma dúzia de idiomas desde o início.(a capacidade de pessoal não técnico adicionar/atualizar traduções seria uma grande vantagem, embora não seja 100% necessária)

• Flexibilidade nos formatos de saída:No mínimo, preciso gerar os documentos (como um todo ou em partes selecionadas) como PDF e HTML.Pontos de bônus para formatos nativos como arquivos de ajuda do Windows.

• Gerenciado e implantado por meio de uma interface de usuário intuitiva (web, de preferência).

Gostaria de saber se vocês conhecem algum sistema que já suporte esse tipo de coisa.Não tenho aversão a escrever isso do zero, mas prefiro não reinventar a roda, se puder.

Os dois principais candidatos que encontrei até agora são Documento e descansar.O primeiro parece ter conquistado a reputação de, bem, ser péssimo.Não estou familiarizado com nenhum deles, mas me disseram que o reST me levaria boa parte do caminho até lá.

Alguma outra sugestão?Seria melhor construir isso do zero?

Answer 1

Posso recomendar o DocBook se você precisar criar documentação técnica tradicional:livros, divididos em capítulos, divididos em seções, etc.Acho que há três coisas principais a considerar:a marcação em si, o conjunto de ferramentas de edição e o conjunto de ferramentas de publicação.

Marcação. A marcação XML do DocBook é muito abrangente, contendo suporte para praticamente todos os aspectos imagináveis ​​que podem ser incluídos em um volume técnico e muito mais.Isso inclui o material básico para livros, como referências cruzadas, notas de rodapé, etc.bem como marcação específica para documentação de software, como listagens de programas, entradas de referência, etc.A referência essencial à marcação é Documento:O Guia Definitivo por Norman Walsh e Leonard Muellner.

O idioma do conteúdo pode ser explicitamente marcado usando lang atributos, para que o documento de origem possa conter o conteúdo em vários idiomas e a versão do idioma desejado possa ser extraída na fase de processamento.

Ferramentas de autoria. Devido ao tamanho do vocabulário DocBook, algum tipo de editor "com reconhecimento de esquema" é praticamente um requisito.Um bom editor irá ajudá-lo com a escolha dos elementos de marcação e garantirá que você produza uma marcação válida.Um editor XML decente servirá, mas dependendo de quão técnicos são os autores de sua documentação, você também pode querer considerar algo mais fácil de usar.Existem alguns editores no estilo WYSIWYG disponíveis.(Eu tenho usado Editor XML XMLMind, e fiquei muito feliz com isso.)

Ferramentas de publicação. A maneira padrão de fato de gerar saída a partir da marcação XML do DocBook é a Documento XSL distribuição de folhas de estilo.Possui suporte para vários formatos de saída, incluindo HTML, XSL-FO (para saída em PDF), Ajuda HTML e até páginas de manual.A saída gerada pela folha de estilo pode ser controlada por vários parâmetros, e a primeira coisa a consultar quando quiser ajustar a saída é o documentação de referência distribuído com as folhas de estilo.

Se e quando você quiser mais controle sobre a saída produzida, entretanto, será necessário personalizar as folhas de estilo XSLT para seu uso específico.Isso pode parecer um tanto assustador, especialmente se você não tiver experiência anterior com XSLT.No entanto, há um excelente livro gratuito disponível sobre o assunto: Documento XSL:O guia completo por Bob Stayton.

Para converter XSL-FO em PDF, você também precisará de um processador XSL-FO.Existe o código aberto e gratuito Apahce FOP e existem várias opções comerciais.

Muito provavelmente, seu processo de publicação acabará parecendo um sistema de construção para sua documentação.Você terá um sistema automatizado (provavelmente conduzido por uma ferramenta de construção como Make ou Ant) que pegará sua fonte de documentação em XML e a transformará nos formatos de saída desejados nas linguagens desejadas.

---

Em resumo, eu diria que o DocBook é uma boa escolha se você deseja produzir documentação técnica detalhada e linear, semelhante a um livro.As principais desvantagens são a complexidade da marcação, que pode apresentar uma curva de aprendizagem considerável para os autores e que pode tornar necessárias ferramentas especiais de autoria.Além disso, personalizar a saída das folhas de estilo DocBook XSL pode ser bastante complicado.

Se você deseja produzir documentação menos "semelhante a um livro" e mais "semelhante a on-line" - tópicos de documentação interligados - você pode querer dar uma olhada em DITA para outra alternativa baseada em XML.Não o usei, mas ele também vem com um conjunto de ferramentas para produzir vários formatos de saída a partir da marcação XML.

Answer 2

DocBook e reestruturado Text são definitivamente os dois maiores concorrentes, mas Asciidoc é outra linguagem de marcação semelhante que é legível, independentemente da marcação. Estou mais familiarizado com (e, portanto, um defensor maior de) reestruturou Text, pessoalmente, mas o ASCIIDOC é apenas mais uma opção por aí.

Dado o que você descreveu até agora, parece Moinmoin seria uma boa opção com base em que tem um analisador reestruturado de text e pode exportar páginas para pdf. Você poderá extrair a fonte e executá-la através de outras ferramentas independentes, conforme necessário (mas pode precisar pré-processá-las para retirar qualquer marcação específica da Moinmoin).

O Google tem alguns outros Resultados para Wiki reestruturada Se Moinmoin não é exatamente o que você precisa.