Alternativati alla Guida HTML

12

Al momento 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 stavo chiedendo 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 posti molto remoti) con il nostro software. Dovrebbe avere un indice (può essere semplice come una pagina html con termini con collegamenti ipertestuali), dovrebbe essere ricercabile e dovrebbe avere un meccanismo che consente di richiamare voci specifiche dal codice (simile alla guida sensibile al contesto).

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

  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 parole 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 la sezione che sono interessato al browser predefinito e quella pagina dovrebbe caricarsi nella sezione corretta.

Le mie esigenze suonano molto come chm - lo fanno. Ho modellato le mie esigenze da chm. L'unica ragione per cui non mi piace chm è a causa del modo in cui il codice interagisce con esso usando mapid e così via. Preferirei piuttosto archiviare una lista di testo semplice (generata automaticamente per me) che il mio codice può utilizzare per accedere alla porzione sensibile al contesto della documentazione.

Sto immaginando uno script che passi attraverso i file di output html e generi una pagina indice che contiene semplicemente un elenco di parole chiave trovate. ovviamente dovrebbe esserci un meccanismo di esclusione delle parole per ignorare parole come: il, è, 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 sia la parte difficile insieme a fornire il meccanismo di ricerca all'interno del browser.

Qualche idea su alternative sarebbe apprezzata. Mi piacerebbe utilizzare un wiki o un insieme di pagine html statiche ospitate su un server web da qualche parte, ma abbiamo un requisito di utilizzo offline critico. Semplicemente posizionando il codice html sul disco locale non ci fornisci i requisiti di ricerca di cui abbiamo bisogno.

Modifica

Progetto software che viene utilizzato dall'industria mineraria. Molte miniere sono molto remote e non hanno accesso a Internet in alcun 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 (ad esempio aiuto sensibile al contesto) lo userei. Sono quasi tentato di scrivere il mio - fondamentalmente sarebbe un wiki portatile. A proposito, se suggerisci una wiki portatile, devi pensare all'utente finale che potrebbe non avere esperienza nell'uso di tali strumenti. Deve essere semplicemente semplice. Quella era la bellezza di chm, è un dolore lavorare con ma piace agli utenti finali.

    
posta bluebill 22.10.2011 - 13:36
fonte

5 risposte

4

Se sei pronto a creare il tuo aiuto nella marcatura XML di DocBook anziché in HTML, DocBook supporta la produzione di WebHelp: link

La documentazione di WebHelp è anche una demo dell'output: link

Offre un formato di guida HTML basato sul Web che include:

  • Ricerca a testo completo con:
    • Supporto per l'inglese, il francese e il tedesco. Il supporto di Stemming può essere aggiunto per altre lingue implementando uno stemmer.
    • Supporto per cinese, giapponese e coreano utilizzando il codice del motore di ricerca Lucene.
    • Cerca evidenziazione che mostra dove viene visualizzato 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 Ant per generare output.
risposta data 28.10.2011 - 15:24
fonte
4

I creatori di RoboHelp hanno continuato con altre cose e sono tornati indietro per fare un'alternativa migliore. Controlla MadCap's Flare - supporta una varietà di formati di output, genera un indice e fornisce una funzione di ricerca che opera localmente (tramite JavaScript).

    
risposta data 07.11.2011 - 01:24
fonte
2

Abbiamo utilizzato Adobe RoboHelp per generare vari stili di documentazione della guida offline. Fornisce molte opzioni di output e di integrazione per il contenuto. La cosa grandiosa di questo strumento è che puoi passare a sviluppatori non esperti e ottenere grandi contenuti con poco sforzo per integrarli nella tua soluzione.

    
risposta data 23.10.2011 - 11:10
fonte
1

Lo stesso CHM sta invecchiando e Microsoft è passata a cose più nuove: link

Ma se vuoi davvero evitare di convertire la tua guida in un sistema esistente e cerchi come fornire una ricerca e una ricerca di parole chiave su file di guida statici, ecco due idee:

  • aggiungi un piccolo server HTTP localhost al progetto per pubblicare 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 di URL personalizzato, ma questo ti legherebbe a un browser e ha molto più lavoro ( e posso dirlo )

  • scrivere un motore di ricerca JavaScript. JavaScript in qualsiasi browser sta diventando piuttosto 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.

risposta data 22.10.2011 - 17:51
fonte
0

What I am looking for is something that can be used off-line (this is important because quite a few of our users are in very remote places) with our software.

Usiamo RoboHelp nella mia azienda e ci auguriamo di rendere i file di aiuto disponibili offline, poiché spesso gli utenti passano da aree con accesso di rete ad aree senza.

It should be searchable and it should have a mechanism that allows specific entries to be called up

Usiamo alcune pagine in RoboHelp per spiegare l'uso di determinati campi su uno schermo. Siamo in grado di avere finestre popup per quei campi che appaiono dopo un clic. RoboHelp ha anche una buona capacità di ricerca e un indice generato automaticamente. Ho sempre avuto fortuna a cercarlo. Questo potrebbe non essere una grande preoccupazione per te, ma siamo in grado di avere qualcuno che aggiorna la documentazione perché RoboHelp è un programma abbastanza facile da usare.

    
risposta data 07.11.2011 - 06:38
fonte

Leggi altre domande sui tag