Alternativas à Ajuda em HTML


12

Atualmente, usamos um sistema chamado AsciiDoc que permite criar documentação em uma simples marcação de texto. A partir disso, podemos gerar vários formatos de saída. Utilizamos apenas os formatos de saída pdf e chm.

Eu queria saber se havia uma alternativa para chm? O que estou procurando é algo que possa ser usado off-line (isso é importante porque muitos de nossos usuários estão em lugares muito remotos) com o nosso software. Ele deve ter um índice (pode ser tão simples quanto uma página html com termos com hiperlink), deve ser pesquisável e deve ter um mecanismo que permita que entradas específicas sejam chamadas a partir do código (semelhante à ajuda sensível ao contexto).

As duas coisas que são contra o PDF nesse caso são:

  1. A ajuda sensível ao contexto não é uma opção
  2. Geralmente o documento é bastante grande
  3. PDF é mais adequado para documentação impressa do que ajuda sensível ao contexto

O que eu gostaria é usar html. O único problema com o html é que não consigo descobrir como fornecer automaticamente uma pesquisa por palavra-chave (além da funcionalidade ctrl + f do navegador - eu gostaria de algo mais aparente). Também não consigo encontrar um método para gerar automaticamente um índice com hiperlink de palavras-chave. A ajuda sensível ao contexto seria simples por causa das tags de seção - eu poderia simplesmente passar o URL da página e da seção que me interessam no navegador padrão e essa página deve carregar na seção correta.

Meus requisitos parecem muito com chm - eles parecem. Eu modelei meus requisitos fora do chm. A única razão pela qual eu não gosto do chm é por causa da maneira como o código interage com ele usando mapids e tal. Eu preferiria usar armazenar uma lista de texto sem formatação (que é gerada automaticamente para mim) que meu código pode usar para acessar a parte sensível ao contexto da documentação.

Estou imaginando um script que percorra os arquivos de saída html e gere uma página de índice que simplesmente contenha uma lista de palavras-chave encontradas. obviamente, deve haver um mecanismo de exclusão de palavras para ignorar palavras como: the, it, is, etc. Esta parte seria relativamente fácil de escrever. A segunda parte precisaria de um script de algum tipo para reunir um banco de dados de palavras-chave e sua localização no texto html. Eu acho que essa seria a parte mais complicada, além de fornecer o mecanismo de pesquisa no navegador.

Qualquer idéia sobre alternativas seria apreciada. Eu adoraria usar um wiki ou um conjunto de páginas html estáticas hospedadas em um servidor da Web em algum lugar, mas temos um requisito crítico de uso offline. Simplesmente colocar o html na unidade local não nos fornece os requisitos de pesquisa necessários.

EDITAR:

Eu desenho software que é usado pela indústria de mineração. Muitas minas são muito remotas e não têm acesso significativo à Internet. Não há nada de errado com pdf, html ou chm (exceto que ele está ficando velho). Se eu pudesse exibir um arquivo pdf no local correto (por exemplo, ajuda sensível ao contexto), eu o usaria. Estou quase tentado a escrever o meu próprio - basicamente, seria um wiki portátil. Por falar nisso, se você sugere um wiki portátil - você deve pensar no usuário final que pode não ter experiência em usar essas ferramentas. Tem que ser muito simples. Essa foi a beleza do chm, é uma dor trabalhar com eles, mas com os usuários finais.


1
O que há de errado em usar uma ferramenta padrão como os navegadores no mecanismo de pesquisa de compilação. Os usuários a entender, é significativamente mais batalha testado em seguida, seu mecanismo de busca personalizado ea interface do usuário é mais familiar aos usuários, em seguida, o seu sistema de busca
Raynos

1
A ajuda do @Raynos Browser geralmente é péssima. O sistema de ajuda padrão no VS2010 é um bom exemplo disso.
MetalMikester 7/11

Respostas:


4

Se você estiver preparado para criar sua ajuda na marcação XML do DocBook em vez de HTML, o DocBook tem suporte para a produção de WebHelp: http://wiki.docbook.org/WebHelp

A documentação do WebHelp também é uma demonstração da saída: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Ele fornece um formato de ajuda HTML baseado na Web que inclui:

  • Pesquisa de texto completo com:
    • Suporte permanente para inglês, francês e alemão. O suporte para stemming pode ser adicionado para outros idiomas implementando um stemmer.
    • Suporte para chinês, japonês e coreano usando o código do mecanismo de pesquisa Lucene.
    • Destaque de pesquisa que mostra onde o termo pesquisado aparece nos resultados.
    • Os resultados da pesquisa podem incluir breves descrições do destino.
  • Painel Sumário com a árvore do sumário dobrável.
  • Sincronização automática do painel de conteúdo e do sumário.
  • Índice e painel de pesquisa implementados sem o uso de um conjunto de quadros.
  • Um arquivo build.xml Ant para gerar saída.

1
Isso é basicamente o que o AsciiDoc faz.
bluebill

4

Os criadores do RoboHelp passaram a outras coisas e voltaram para fazer uma alternativa melhor. Confira o Flare do MadCap - ele suporta uma variedade de formatos de saída, gera um índice e fornece uma função de pesquisa que opera localmente (via JavaScript).


2

Estamos usando o Adobe RoboHelp para gerar vários estilos de documentação de ajuda offline. Ele fornece muitas opções de saída e integração para o conteúdo. O melhor dessa ferramenta é que você pode entregá-la a não desenvolvedores e obter um ótimo conteúdo com pouco esforço integrado à sua solução.


1

O próprio CHM está ficando velho e a Microsoft também mudou para coisas mais recentes: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Mas se você realmente deseja evitar converter sua ajuda para um sistema existente e está procurando como fornecer uma pesquisa e pesquisa de palavras-chave em arquivos de ajuda estáticos, aqui estão duas idéias:

  • adicione um pequeno servidor HTTP somente localhost ao projeto para servir um site com a documentação. Os problemas são quando ou como iniciar / parar este servidor HTTP e / ou mantê-lo em execução. Uma alternativa seria implementar um esquema de URL personalizado, mas isso o ligaria a um navegador e é muito mais trabalhoso ( e posso dizer )

  • escreva um mecanismo de pesquisa JavaScript. Atualmente, o JavaScript em qualquer navegador está ficando muito rápido e com bom desempenho. Um índice de palavras-chave pode ser facilmente armazenado em JSON, e eu executei expressons regulares em arquivos locais com bons resultados.


Eu estava pensando ao longo das linhas de um mecanismo de busca javascript. Vou ter que fazer mais algumas pesquisas.
bluebill

0

O que estou procurando é algo que possa ser usado off-line (isso é importante porque muitos de nossos usuários estão em lugares muito remotos) com o nosso software.

Usamos o RoboHelp na minha empresa e temos sorte em disponibilizar os arquivos de ajuda offline, pois geralmente temos usuários que vão de áreas com acesso à rede para áreas sem.

Deve ser pesquisável e deve ter um mecanismo que permita que entradas específicas sejam chamadas

Usamos algumas páginas no RoboHelp para explicar o uso de determinados campos em uma tela. Podemos ter pop-ups para os campos que aparecem após um clique. O RoboHelp também possui uma capacidade de pesquisa muito boa e um índice gerado automaticamente. Eu sempre tive boa sorte pesquisando com ele. Isso pode não ser uma grande preocupação para você, mas é possível que alguém atualize a documentação, porque o RoboHelp é um programa bastante fácil de usar.

Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.