Si alterna alla Guida HTML


12

Attualmente utilizziamo un sistema chiamato AsciiDoc che ci consente di creare documentazione in un semplice markup di testo. Da ciò possiamo generare più formati di output. Utilizziamo solo i formati di output pdf e chm.

Mi chiedevo se ci fosse un'alternativa a chm? Quello che sto cercando è qualcosa che può essere usato off-line (questo è importante perché molti dei nostri utenti sono in luoghi molto remoti) con il nostro software. Dovrebbe avere un indice (può essere semplice come una pagina html con termini ipertestuali), dovrebbe essere ricercabile e dovrebbe avere un meccanismo che consenta di richiamare voci specifiche dal codice (simile alla guida sensibile al contesto).

Le due cose che sono contro PDF in questo caso è:

  1. La guida sensibile al contesto non è un'opzione
  2. Generalmente il documento è piuttosto grande
  3. Il PDF è più adatto alla documentazione stampata rispetto alla guida sensibile al contesto

Quello che vorrei è usare HTML. L'unico problema con html è che non riesco a capire come fornire automaticamente una ricerca per parola chiave (oltre alla funzionalità ctrl + f del browser, vorrei qualcosa di più evidente). Inoltre, non riesco a trovare un metodo per generare automaticamente un indice ipertestuale di parole chiave. La guida sensibile al contesto sarebbe semplice a causa dei tag della sezione: potrei semplicemente passare l'URL della pagina e della sezione che mi interessano nel browser predefinito e quella pagina dovrebbe caricare fino alla sezione corretta.

Le mie esigenze suonano moltissimo come chm - lo fanno. Ho modellato le mie esigenze su chm. L'unico motivo per cui non mi piace chm è a causa del modo in cui il codice interagisce con esso usando mapids e simili. Preferirei di gran lunga utilizzare un elenco di testo semplice (che viene generato automaticamente per me) che il mio codice può utilizzare per accedere alla parte sensibile della contesto della documentazione.

Sto immaginando uno script che attraversi i file di output html e generi una pagina di indice che contenga semplicemente un elenco di parole chiave che ha trovato. ovviamente ci dovrebbe essere un meccanismo di esclusione delle parole per ignorare parole come: the, it, is, ecc. Questa parte sarebbe relativamente facile da scrivere. La seconda parte avrebbe bisogno di uno script di qualche tipo per mettere insieme un database di parole chiave e la loro posizione all'interno del testo HTML. Penso che questa sarebbe la parte difficile insieme a fornire il meccanismo di ricerca all'interno del browser.

Qualsiasi idea sulle alternative sarebbe apprezzata. Mi piacerebbe usare un wiki o un insieme di pagine html statiche ospitate su un server web da qualche parte, ma abbiamo un requisito fondamentale per l'utilizzo offline. Il semplice posizionamento dell'html sull'unità locale non ci fornisce i requisiti di ricerca di cui abbiamo bisogno.

MODIFICARE:

Progetto software utilizzato dall'industria mineraria. Molte miniere sono molto remote e non hanno accesso a Internet in modo significativo. Non c'è niente di sbagliato in pdf o html o chm (tranne che sta invecchiando). Se potessi visualizzare un file pdf nella posizione corretta (es. Aiuto sensibile al contesto) lo userei. Sono quasi tentato di scrivere il mio - fondamentalmente sarebbe un wiki portatile. A proposito, se suggerisci un wiki portatile, devi pensare all'utente finale che potrebbe non avere esperienza nell'uso di tali strumenti. Deve essere morto semplice. Questa è stata la bellezza di chm, è un dolore lavorare con ma piace agli utenti finali.


1
Cosa c'è di sbagliato nell'usare uno strumento standard come i browser nel meccanismo di ricerca della build. Gli utenti comprendono che è significativamente più testato in battaglia rispetto al tuo meccanismo di ricerca personalizzato e l'interfaccia utente è più familiare agli utenti rispetto al tuo sistema di ricerca
Raynos,

1
L'aiuto basato su browser @Raynos di solito fa schifo piuttosto male. Il sistema di aiuto predefinito in VS2010 ne è un buon esempio.
MetalMikester

Risposte:


4

Se sei pronto a creare il tuo aiuto nel markup XML di DocBook anziché in HTML, DocBook ha il supporto per la produzione di WebHelp: http://wiki.docbook.org/WebHelp

La documentazione di WebHelp è anche una demo dell'output: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Ti offre un formato di aiuto HTML basato sul Web che include:

  • Ricerca a testo integrale con:
    • Supporto di supporto per inglese, francese e tedesco. Il supporto per lo stemming può essere aggiunto per altre lingue implementando uno stemmer.
    • Supporto per cinese, giapponese e coreano utilizzando il codice del motore di ricerca Lucene.
    • Evidenzia ricerca che mostra dove appare il termine cercato nei risultati.
    • I risultati della ricerca possono includere brevi descrizioni del target.
  • Riquadro del sommario con albero TOC comprimibile.
  • Sincronizzazione automatica del riquadro del contenuto e del sommario.
  • TOC e riquadro di ricerca implementati senza l'uso di un set di frame.
  • Un file build.xml di Ant per generare output.

1
Questo è fondamentalmente ciò che fa AsciiDoc.
bluebill,

4

I creatori di RoboHelp sono passati ad altre cose e sono tornati in giro per fare un'alternativa migliore. Dai un'occhiata a MadCap's Flare : supporta una varietà di formati di output, genera un indice e fornisce una funzione di ricerca che opera localmente (tramite JavaScript).


2

Abbiamo utilizzato Adobe RoboHelp per generare vari stili di documentazione di aiuto offline. Fornisce molte opzioni di output e integrazione per i contenuti. La cosa grandiosa di questo strumento è che puoi consegnarlo a non sviluppatori e ottenere grandi contenuti con il minimo sforzo si integra nella tua soluzione.


1

CHM stesso sta invecchiando e Microsoft è passata anche a cose più recenti: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Ma se vuoi davvero evitare di convertire il tuo aiuto in un sistema esistente e stai cercando come fornire una ricerca e una ricerca di parole chiave su file di aiuto statici, ecco due idee:

  • aggiungere un piccolo server HTTP solo localhost al progetto per servire un sito Web con la documentazione. I problemi sono quando o come avviare / arrestare questo server HTTP e / o mantenerlo in esecuzione. Un'alternativa sarebbe implementare uno schema URL personalizzato, ma questo ti legherebbe a un browser ed è molto più lavoro ( e posso dire )

  • scrivere un motore di ricerca JavaScript. JavaScript in qualsiasi browser sta diventando abbastanza veloce e performante in questi giorni. Un indice di parole chiave potrebbe essere facilmente memorizzato su JSON e ho eseguito espressioni regolari su file locali con risultati piuttosto buoni.


Stavo pensando sulla falsariga di un motore di ricerca javascript. Dovrò fare qualche ricerca in più.
bluebill,

0

Quello che sto cercando è qualcosa che può essere usato off-line (questo è importante perché molti dei nostri utenti sono in luoghi molto remoti) con il nostro software.

Usiamo RoboHelp presso la mia azienda e siamo fortunati a rendere i file di aiuto disponibili offline poiché spesso abbiamo utenti che passano da aree con accesso alla rete ad aree senza.

Dovrebbe essere ricercabile e dovrebbe avere un meccanismo che consenta di richiamare voci specifiche

Utilizziamo alcune pagine di RoboHelp per spiegare l'uso di determinati campi su uno schermo. Siamo in grado di avere popup per quei campi che compaiono dopo un clic. RoboHelp ha anche una capacità di ricerca molto bella e un indice generato automaticamente. Ho sempre avuto fortuna a cercarlo. Questo potrebbe non essere un grosso problema per te, ma siamo in grado di far aggiornare la documentazione a chiunque perché RoboHelp è un programma abbastanza facile da usare.

Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.