Sometimes, a few lines of JavaScript is all it takes to make an online help system more friendly. Footnotes and glossary terms displayed on mousever, sections of a page presented as horizontal tabs, additional information that can be revealed or hidden on click — all of these are things that enhance UX.
And then, there's you, the writer. What about WX (writer experience)? What if there was a way to write something once, and then reuse it across multiple files in the same folder? Everyone says you need DITA for that, but that's not true. HTML has something called transclusion that was made just for this scenario. Include a few of lines of JavaScript to your HTML files, and you have the conref feature of DITA right in HTML.
Code samples and example implementations are available for download from GitHub.
The files use the jQuery and the jQuery UI libraries, and are implemented through the class attribute of HTML elements. Therefore, you can use these effects of any element that can take a class attribute.
| Effect | When to use | Working example |
|---|---|---|
| Write once, call anywhere. DITA-like content referencing (conref) | To do away with copy-paste of frequently repeated content, by implementing DITA-like content referencing | conref.html |
| Show or hide blocks of content on click | To provide additional information without otherwise breaking the flow of a bit of text in a topic | twistie.html |
| Display the text of a footnote on mouseover | To give an option to the reader to not jump up and down within the document, but rather to stay within the context of the paragraph currently being read | fnotehovertext.html |
| Show the several sections of a page as tabs | To give the reader an immediate overview of the page content, and the facility to navigate between the page sections without needed to scroll up and down | tabbedsections.html |