LibreOffice Writer Basics Technical writing and user manuals Part 1

Word processors and page layout programs are now so mature and powerful that companies can use them for writing user manuals and documentation. There has been hype about using DITA or producing documents using single-source publishing applications such as MadCap Flare, but the truth is you dont have to pay for these applications. The Surface Pro 4 PDF User Guide and Intel NUC setup guide, for example, were written using Word (2016 and 2013 respectively).

Companies and organizations stick to an application such as FrameMaker because their staff have gotten used to it, despite the output not really requiring variables or advanced XML functionality. Western Digitals user manual for My Cloud is a straightforward document that could have been produced using any word processor or page layout program - the company could have saved several hundred dollars instead of paying for FrameMaker 2015.

LibreOffice Writer , which is part of LibreOffice, is freely available for different platforms, mature, and incredibly functional. Moreover, you can publish not only to PDF but to enterprise-friendly XHTML/ HTML5, ebook supported ePUB via plugins, and the education/science-community supported LaTeX format.

This article discusses common tasks associated with writing consumer and enterprise technical  documentation. This article uses LibreOffice Writer 5.2.x installed on openSUSE 42.x Gnome and LibreOffice Writer 4.3.x for Debian 8 Xfce.

Admonitions

Technical documentation today uses admonitions such as notes, tips, and warnings, rather than the more traditional footnotes. Footnotes and endnotes are somewhat unwieldy when a document is read on mobile devices such as smartphones and ebook readers. Admonitions, on the other hand, are directly read next to the associated text.

Admonitions can simply be text se parated from the main text flow by different left and right margins, and set off with NOTE, TIP, WARNING, or IMPORTANT with a colon. However, adding a boundary, a box, or a custom icon is a popular practice.

In LibreOffice Writer, you can use one of the following methods to format admonitions:

• Frame - Frames are extremely flexible in terms of formatting and look great when the document is outputted to PDF. Frames need a bit of work to appear properly in ePUB or HTML however.
• Tables - Tables have long been used for admonitions in writing documentation meant for HTML and print. No additional tweaking is required when exporting to ePUB and PDF.
• Text box - Writers Text boxes dont support images, but they are simple to use and work well for PDF, though they might have formatting issues in XHTML or ePUB. 

The admonitions in the screen capture were created using a Frame, a table, and Text box. The left window shows the PDF output.

 Continued in LibreOffice Writer Basics: Technical writing and user manuals Part 2