XML o HTML per Manuale utente / Guida e perché?

In realtà, vorrei andare per entrambi.

Stiamo scrivendo grandi manuali per un sistema militare e DocBook con le sue possibilità di trasformazione è grandioso. Non creare il tuo schema, utilizzare quello completo che DocBook ha ed esportare in HTML, PDF, Latex, ecc.

Anche l'archiviazione di cose in DocBook ha l'enorme vantaggio che è solo testo, il che significa che è ragionevole memorizzarlo in CVS, i relativi ticket bugtracker, ecc. Nel lungo periodo, per grandi manuali, questo è solo il modo andare.

Funziona alla grande.

XML consente di definire elementi personalizzati che è possibile utilizzare per trasformare in HTML utilizzando XSLT (XSLT viene utilizzato per trasformare i dati XML da un formato all'altro). Questo è più flessibile, ma anche più lavoro.

Ad esempio: se si utilizza il percorso XML, è possibile definire nuovi elementi in un XSD (XSD è dove è possibile definire nuovi elementi) e il documento potrebbe essere scritto in questo modo:

<HelpHeader>Ron's Help manual</HelpHeader>
<Warning level="5">Not to be taken internally!!</Warning>
<HelpBody>Welcome to the Help Manual!
        <HelpSidebar>I hope this documen is very helpful to you<HelpSidebar/>
</HelpBody>

Questo potrebbe rendere più facile scrivere il documento poiché gli elementi sono più vicini al documento che stai scrivendo. Devi quindi utilizzare XSLT per trasformare il documento in HTML (e penso che tu possa includere anche CSS e forse JavaScript anche qui?), Il che potrebbe richiedere molto lavoro.

Uno dei vantaggi del passaggio XML è che se decidi di cambiare layout / aspetto, non cambi il contenuto del tuo file XML, cambi le traduzioni XML-to-HTML nel File XSL. In questo modo il contenuto viene preservato e le modifiche di stile enormi e radicali possono essere fatte abbastanza facilmente. Questo è un grande vantaggio quando i cambiamenti di stile sono relativamente piccoli, ma ci sono centinaia di file HTML. Puoi apportare una modifica all'XSL e rigenerare l'HTML con un solo clic del mouse! Nessuno vuole riapplicare manualmente le modifiche HTML a tutti quei file.

Suggerirò di utilizzare Markdown perché puoi scrivere un testo semplice e convertirlo in HTML per te. Puoi usare WriteMonkey per scrivere del testo usando la sintassi Markdown ed esportarlo in HTML. Per una documentazione semplice, questo potrebbe essere tutto ciò di cui hai bisogno.

Se ti piace il codice XML, utilizza Docbook , quindi puoi generare, HTML, PDF, CHM o qualsiasi altra cosa.

Altre alternative a XML che sono facili da generare vari output sono Markdown , Textile e altri linguaggi di markup basati sulla sintassi simile a Wiki.

Dovresti concentrarti su qualcosa che possa indirizzare i formati più diversi per l'output finale come ad esempio ePub.