Alternativas a la Ayuda HTML

Actualmente utilizamos un sistema llamado AsciiDoc que nos permite crear documentación en un simple marcado de texto. A partir de eso podemos generar múltiples formatos de salida. Solo utilizamos los formatos de salida pdf y chm.

Me preguntaba si había una alternativa a chm? Lo que estoy buscando es algo que se pueda usar fuera de línea (esto es importante porque algunos de nuestros usuarios están en lugares muy remotos) con nuestro software. Debe tener un índice (puede ser tan simple como una página html con términos con hipervínculos), debe poder buscarse y debe tener un mecanismo que permita que se invoquen entradas específicas desde el código (similar a la ayuda sensible al contexto).

Las dos cosas que están en contra de PDF en este caso son:

1. La ayuda sensible al contexto no es una opción
2. Generalmente el documento es bastante grande
3. PDF es más adecuado para la documentación impresa que la ayuda contextual

Lo que me gustaría es usar html. El único problema con html es que parece que no puedo entender cómo proporcionar automáticamente una búsqueda de palabras clave (aparte de la funcionalidad ctrl + f de los navegadores, me gustaría algo más aparente). Tampoco puedo encontrar un método para generar automáticamente un índice hipervinculado de palabras clave. La ayuda sensible al contexto sería simple debido a las etiquetas de sección: simplemente podría pasar la URL de la página y la sección que me interesa al navegador predeterminado y esa página debería cargarse en la sección correcta.

Mis requisitos se parecen mucho a chm, lo hacen. Modelé mis requisitos fuera de chm. La única razón por la que no me gusta chm es por la forma en que el código interactúa con los mapids y demás. Preferiría usar almacenar una lista de texto sin formato (que se genera automáticamente para mí) que mi código puede usar para acceder a la parte sensible al contexto de la documentación.

Estoy imaginando un script que pasaría por los archivos de salida html y generaría una página de índice que simplemente contiene una lista de palabras clave que encontró. obviamente debería haber un mecanismo de exclusión de palabras para ignorar palabras como: the, it, is, etc. Esta parte sería relativamente fácil de escribir. La segunda parte necesitaría un script de algún tipo para reunir una base de datos de palabras clave y su ubicación dentro del texto html. Creo que esta sería la parte difícil junto con proporcionar el mecanismo de búsqueda dentro del navegador.

Cualquier idea sobre alternativas sería apreciada. Me encantaría usar un wiki o un conjunto de páginas html estáticas alojadas en un servidor web en algún lugar, pero tenemos un requisito crítico de uso fuera de línea. Simplemente colocar el html en el disco local no nos proporciona los requisitos de búsqueda que necesitamos.

EDITAR:

Diseño software que es usado por la industria minera. Muchas minas son muy remotas y no tienen acceso a Internet de ninguna manera significativa. No hay nada malo con pdf o html o chm (excepto que se está volviendo viejo). Si pudiera mostrar un archivo pdf en la ubicación correcta (es decir, ayuda sensible al contexto) lo usaría. Estoy casi tentado a escribir el mío, básicamente sería un wiki portátil. Hablando de eso, si sugiere una wiki portátil, debe pensar en el usuario final que puede no tener experiencia en el uso de tales herramientas. Tiene que ser muy simple. Esa fue la belleza de chm, es un trabajo difícil pero a los usuarios finales les gusta.

Si está preparado para crear su ayuda en el marcado XML de DocBook en lugar de HTML, DocBook tiene soporte para producir WebHelp: http://wiki.docbook.org/WebHelp

La documentación de WebHelp también es una demostración de la salida: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Le ofrece un formato de ayuda HTML basado en la web que incluye:

• Búsqueda de texto completo con:
  • Soporte de Stemming para inglés, francés y alemán. Se puede agregar compatibilidad con Stemming para otros idiomas implementando un stemmer.
  • Soporte para chino, japonés y coreano usando el código del motor de búsqueda Lucene.
  • Búsqueda resaltada que muestra dónde aparece el término buscado en los resultados.
  • Los resultados de la búsqueda pueden incluir descripciones breves del objetivo.
• Panel de tabla de contenido con árbol TOC plegable.
• Sincronización automática de panel de contenido y TOC.
• TOC y panel de búsqueda implementado sin el uso de un conjunto de marcos.
• Un archivo Ant build.xml para generar resultados.

Los creadores de RoboHelp pasaron a otras cosas y han regresado para hacer una mejor alternativa. Echa un vistazo a Flare de MadCap : admite una variedad de formatos de salida, genera un índice y proporciona una función de búsqueda que funciona localmente (a través de JavaScript).

Hemos estado utilizando Adobe RoboHelp para generar varios estilos de documentación de ayuda sin conexión. Proporciona muchas opciones de salida e integración para el contenido. Lo mejor de esta herramienta es que puede entregarla a los que no son desarrolladores y obtener un excelente contenido con poco esfuerzo se integra en su solución.

CHM en sí mismo está envejeciendo, y Microsoft también se ha movido a cosas más nuevas: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Pero si realmente desea evitar convertir su ayuda a un sistema existente y está buscando cómo proporcionar una búsqueda y búsqueda de palabras clave en archivos de ayuda estáticos, aquí hay dos ideas:

• agregue un pequeño servidor HTTP solo localhost al proyecto para servir un sitio web con la documentación. Los problemas son cuándo o cómo iniciar / detener este servidor HTTP y / o mantenerlo en funcionamiento. Una alternativa sería implementar un esquema de URL personalizado, pero esto lo vincularía a un navegador y es mucho más trabajo ( y puedo decir )

• escribe un buscador de JavaScript. JavaScript en cualquier navegador se está volviendo bastante rápido y eficiente en estos días. Un índice de palabras clave podría almacenarse fácilmente en JSON, y he ejecutado expresiones regulares en archivos locales con muy buenos resultados.

Lo que estoy buscando es algo que se pueda usar fuera de línea (esto es importante porque algunos de nuestros usuarios están en lugares muy remotos) con nuestro software.

Usamos RoboHelp en mi empresa y tenemos suerte de que los archivos de ayuda estén disponibles sin conexión, ya que a menudo tenemos usuarios que van de áreas con acceso a la red a áreas sin acceso.

Debe poder buscarse y debe tener un mecanismo que permita llamar entradas específicas

Usamos algunas páginas en RoboHelp para explicar el uso de ciertos campos en una pantalla. Podemos tener ventanas emergentes para esos campos que aparecen después de un clic. RoboHelp también tiene una capacidad de búsqueda muy buena y un índice generado automáticamente. Siempre he tenido buena suerte buscando con eso. Puede que esto no sea una gran preocupación para usted, pero podemos hacer que cualquiera actualice la documentación porque RoboHelp es un programa bastante fácil de usar.