Strumenti di authoring della guida utente finale multipiattaforma

Question

Quali sono alcuni buoni strumenti di authoring per creare file di guida multipiattaforma per gli utenti finali? (La nostra applicazione utilizza il framework Qt, se questo fa alcuna differenza.)

Nota: non sono interessato alla documentazione interna dell'API - stiamo usando doxygen per quello.

Idealmente, una soluzione sarebbe:

• ci permettono di gestire tutti i contenuti di aiuto (testo, una tabella di contenuti, immagini, ecc) in un unico luogo.
• Output per i formati della guida nativi. (CHM per Windows - o almeno qualcosa che potremmo alimentare direttamente nell'Help della Guida HTML, non so quali siano i formati di aiuto "standard" delle altre piattaforme.)
• Supporto WYSIWYG decente: gestire l'immissione di testo comune, le immagini, riferimenti, ecc. facilmente, ma possiamo modificare l'HTML quando è necessario.
• Formato di file basato su testo per il progetto di aiuto (XML, ecc.) In modo che possa essere versionato in Subversion.
• Qualsiasi hook che aiuti a mantenerlo sincronizzato con la base di codice effettiva sarebbe ottimo. (Forse in qualche modo un argomento della guida è associato a un file di codice e può controllare Subversion per vedere se sono state apportate modifiche e contrassegnare un argomento come "probabilmente non aggiornato" ... sto sognando?)
• Il contenuto della guida può essere localizzato
• Non contrario al prodotto commerciale, ma un'opzione gratuita sarebbe piacevole.

I'll go ahead e rendere questo un wiki e iniziare con alcuni esempi. Vota su o giù se hai esperienza con loro e lascia dei commenti. Aggiungi anche altri strumenti.

Answer 1

Ho appena scoperto Sphinx; Penso di essere innamorato.

• Meglio di WYSIWYG su HTML: reStructuredText
• Uscite per QtHelp (tra l'altro), così sarà facile per distribuire (e integrare) nella nostra applicazione.
• Non siamo ancora sicuri della localizzazione, ma attraverseremo quel ponte quando è necessario.
• Era facile da configurare e "funziona solo"; sembra professionale

Answer 2

Robohelp

Answer 3

Help & Manual

Answer 4

L'unico che conosco è Latex, uno dei convertitori di latex2html e quindi alcuni adattamenti per rendere l'html risultante pronto per l'archiver CHM.

• testo, html, chm, pdf, ps nessun problema.
• La conversione in Word tramite RTF era un disastro, non si conosce lo stato corrente.
• convertitori di latex 2 html, mentre diversi, tutti hanno i loro problemi.
• I file PDF sono assolutamente fantastici.
• WYSIWYM (via lyx) possibile.

Questo archivio ha un gruppo di CHMs questo modo (segnatamente le prog, ref e contiene parti, il resto (RTL, FCL, LCL) sono generati dal nostro doxygen equivalente, fpdoc)

http://www.stack.nl/~marcov/doc-chm.zip

Si noti che i CHM precedenti sono realizzati con il nostro compilatore CHM (portatile). Sì, non più workshop.

documento A Lyx in formato PDF e HTML:

pdf: http://www.stack.nl/~marcov/buildfaq.pdf

html: http://www.stack.nl/~marcov/buildfaq/

Answer 5

ho usato RoboHelp per anni.

Va bene, ma la tecnologia di base è molto vecchia ora. Anche il modo in cui si bloccano alle versioni di Word è un totale PITA (e mi ha costretto a evitare più volte gli aggiornamenti degli MS Office).

Ci stiamo muovendo per Madcap divampare http://www.madcapsoftware.com/products/flare/robohelp.aspx

Answer 6

penso DocBook indirizzi tutti voi requisiti tranne forse i ganci di sincronizzazione, che ci penserò un po 'più avanti. È essenzialmente un sottoinsieme di XML progettato per la creazione di documentazione ed è gratuito e open source. È solo un formato più una serie di trasformazioni di output XSL che convertono il Docbook in formati più utili (HTML e quindi CHM, JavaHelp, PDF via XML-FO o Tex).

Ciò significa che è ancora necessario scegliere uno strumento di authoring XML per modificarlo in modo che funzioni come WYSIWYG dipenderanno dalle funzionalità del software di authoring XML. Usiamo Syntext Serna in quanto ha un buon supporto per WYSIWYG e la modifica in linea di #include XML (nessun altro sembra supportare quest'ultimo). Potresti trovare altri strumenti di authoring XML più adatti alle tue esigenze: Serna è un'offerta commerciale ragionevolmente costosa.

Docbook offre molta flessibilità tramite la profilazione, che consente di includere/escludere elementi xml in base ai relativi attributi. I casi d'uso di esempio dovrebbero avere un output di guida leggermente diverso per OS = Windows rispetto a OS = Linux. La localizzazione è supportata anche tramite la profilazione e altri meccanismi.

Un discreto numero introduction to Docbook può essere trovato here.

Utilizziamo Docbook per il nostro formato di guida e lo compilo in file CHM che contengono solo aiuto per le funzionalità relative a un prodotto specifico (ad esempio, l'edizione Enterprise ha funzionalità che non sono nelle versioni Standard o Demo). Le fasi rilevanti sono:

1. Eseguire i modelli di profilo XSL sull'origine XML (utilizzando ad esempio XSLTproc).
2. Eseguire i modelli XSL della Guida HTML sull'output di 1.
3. Compilare i file HTML di output utilizzando il compilatore della Guida HTML di Microsoft (HHC).