Alternatif à l'aide HTML

Nous utilisons actuellement un système appelé AsciiDoc qui nous permet de créer de la documentation dans un simple balisage de texte. À partir de cela, nous pouvons générer plusieurs formats de sortie. Nous utilisons uniquement les formats de sortie pdf et de sortie chm.

Je me demandais s'il y avait une alternative à chm? Ce que je recherche, c'est quelque chose qui peut être utilisé hors ligne (c'est important parce que bon nombre de nos utilisateurs sont dans des endroits très éloignés) avec notre logiciel. Il doit avoir un index (il peut être aussi simple qu'une page html avec des termes hyperliens), il doit être consultable et il doit avoir un mécanisme qui permet d'appeler des entrées spécifiques à partir du code (similaire à l'aide contextuelle).

Les deux choses qui sont contre PDF dans ce cas sont:

1. L'aide contextuelle n'est pas une option
2. Généralement, le document est assez volumineux
3. Le PDF est plus adapté à la documentation imprimée qu'à l'aide contextuelle

Ce que je voudrais, c'est utiliser du HTML. Le seul problème avec html est que je n'arrive pas à comprendre comment fournir automatiquement une recherche par mot-clé (autre que la fonctionnalité ctrl + f des navigateurs - je voudrais quelque chose de plus apparent). Je n'arrive pas non plus à trouver une méthode pour générer automatiquement un index hyperlien de mots clés. L'aide contextuelle serait simple à cause des balises de section - je pourrais simplement passer l'url de la page et de la section qui m'intéressent dans le navigateur par défaut et cette page devrait se charger dans la bonne section.

Mes exigences ressemblent énormément à chm - elles le font. J'ai modélisé mes besoins sur chm. La seule raison pour laquelle je n'aime pas chm est la façon dont le code interagit avec lui à l'aide de mapids et autres. Je préfère de loin utiliser stocker une liste de texte brut (qui est automatiquement générée pour moi) que mon code peut utiliser pour accéder à la partie contextuelle de la documentation.

J'imagine un script qui passerait par les fichiers de sortie html et générerait une page d'index qui contient simplement une liste de mots clés qu'il a trouvés. évidemment, il devrait y avoir un mécanisme d'exclusion de mots pour ignorer les mots comme: le, il, est, etc. Cette partie serait relativement facile à écrire. La deuxième partie aurait besoin d'un script quelconque pour constituer une base de données de mots-clés et leur emplacement dans le texte html. Je pense que ce serait la partie délicate avec la fourniture du mécanisme de recherche dans le navigateur.

Toute idée d'alternative serait appréciée. J'aimerais utiliser un wiki ou un ensemble de pages html statiques hébergées sur un serveur Web quelque part, mais nous avons une exigence critique d'utilisation hors ligne. Le simple fait de placer le code HTML sur le disque local ne nous fournit pas les exigences de recherche dont nous avons besoin.

ÉDITER:

Je conçois des logiciels utilisés par l'industrie minière. De nombreuses mines sont très éloignées et n'ont pas accès à Internet de manière significative. Il n'y a rien de mal avec pdf, html ou chm (sauf qu'il vieillit). Si je pouvais afficher un fichier pdf au bon endroit (c'est-à-dire une aide contextuelle), je l'utiliserais. Je suis presque tenté d'écrire le mien - en gros, ce serait un wiki portable. En parlant de cela, si vous proposez un wiki portable - vous devez penser à l'utilisateur final qui n'a peut-être aucune expérience de l'utilisation de tels outils. Il faut que ce soit simple. C'était la beauté de chm, c'est difficile de travailler avec mais les utilisateurs finaux aiment ça.

Si vous êtes prêt à créer votre aide dans le balisage XML DocBook plutôt qu'en HTML, DocBook prend en charge la production de WebHelp: http://wiki.docbook.org/WebHelp

La documentation WebHelp est également une démonstration de la sortie: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Il vous donne un format d'aide HTML basé sur le Web qui comprend:

• Recherche plein texte avec:
  • Prise en charge de la racine pour l'anglais, le français et l'allemand. Le support de la racine peut être ajouté pour d'autres langues en implémentant un stemmer.
  • Prise en charge du chinois, du japonais et du coréen à l'aide du code du moteur de recherche Lucene.
  • Mise en surbrillance de la recherche qui montre où le terme recherché apparaît dans les résultats.
  • Les résultats de la recherche peuvent inclure de brèves descriptions de la cible.
• Volet de la table des matières avec arborescence de table des matières repliable.
• Synchronisation automatique du volet de contenu et de la table des matières.
• TOC et volet de recherche mis en œuvre sans l'utilisation d'un jeu de cadres.
• Un fichier Ant build.xml pour générer une sortie.

Les créateurs de RoboHelp sont passés à autre chose et sont revenus pour faire une meilleure alternative. Découvrez Flare de MadCap - il prend en charge une variété de formats de sortie, génère un index et fournit une fonction de recherche qui fonctionne localement (via JavaScript).

Nous utilisons Adobe RoboHelp pour générer différents styles de documentation d'aide hors ligne. Il fournit de nombreuses options de sortie et d'intégration pour le contenu. La grande chose à propos de cet outil est que vous pouvez le remettre à des non-développeurs et obtenir un excellent contenu avec peu d'efforts s'intègre dans votre solution.

CHM lui-même vieillit et Microsoft est également passé à des nouveautés: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Mais si vous voulez vraiment éviter de convertir votre aide en un système existant et que vous cherchez à fournir une recherche et une recherche par mot-clé sur des fichiers d'aide statiques, voici deux idées:

• ajouter un petit serveur HTTP localhost uniquement au projet pour servir un site Web avec la documentation. Les problèmes sont quand ou comment démarrer / arrêter ce serveur HTTP et / ou le faire fonctionner. Une alternative serait d'implémenter un schéma d'URL personnalisé, mais cela vous lierait à un navigateur et c'est beaucoup plus de travail ( et je peux le dire )

• écrire un moteur de recherche JavaScript. JavaScript dans n'importe quel navigateur devient assez rapide et performant ces jours-ci. Un index de mots clés pourrait être facilement stocké sur JSON, et j'ai exécuté des expressons réguliers sur des fichiers locaux avec de très bons résultats.

Ce que je recherche, c'est quelque chose qui peut être utilisé hors ligne (c'est important parce que bon nombre de nos utilisateurs sont dans des endroits très éloignés) avec notre logiciel.

Nous utilisons RoboHelp dans mon entreprise et nous avons de la chance de rendre les fichiers d'aide disponibles hors ligne, car nous avons souvent des utilisateurs allant de zones avec accès réseau à des zones sans.

Il doit être consultable et il doit avoir un mécanisme qui permet d'appeler des entrées spécifiques

Nous utilisons certaines pages de RoboHelp pour expliquer l'utilisation de certains champs sur un écran. Nous pouvons avoir des fenêtres contextuelles pour les champs qui apparaissent après un clic. RoboHelp a également une très belle capacité de recherche et un index généré automatiquement. J'ai toujours eu de la chance de chercher avec ça. Ce n'est peut-être pas une préoccupation majeure pour vous, mais nous pouvons demander à quiconque de mettre à jour la documentation car RoboHelp est un programme assez facile à utiliser.