Tips on Writing a Manual or Guide using LyX Part 1

Category: Techwriter

Writing a document using LyX can be a frustrating experience if you're accustomed to a traditional word processor like Abiword, Microsoft Word, or LibreOffice Write. However, there's a lot to like about using the WYSIWYM LyX. As mentioned in a previous blogpost about using CherryTree for quickly writing online manuals, there are many ways to write a structured document without having to use markup such as Docbook or XML. As much as I like HTML5, Docbook, and DITA, I must admit it's a bit too much if you're going to write a manual that won't have reusable sections, won't access extensible data, or won't be repurposed for different mediums. For technical writers who are currently using WYSIWYG page layout applications like Adobe PageMaker, Adobe InDesign, or even Microsoft Publisher and CorelDraw, there's a definite advantage to using LyX's approach. For one thing, I find it frustrating having to constantly think about spacing, typography, and layout with those applications as opposed to rattling off text (with or without markup). That said, LyX does have its limitations from a design perspective even when compared to the basic word processors such as Corel WordPerfect and Microsoft Word 2010.

Before attempting to use LyX to write a document, make sure you're aware of its primary function - clean and straightforward typesetting (This is actually laborious to pull of when using XSLT). Think of LyX as a distraction-free text editor with the ability to export a structured PDF. I really like LyX, but with the cornucopia of fantastic open source full-featured word processors out there, I only use it for special cases such as textbooks or scholarly documents requiring mathematical symbols. For my part, the most useful feature for LyX is exporting a clean PDF with a navigable TOC without much effort. LyX also exports to a pretty clean single page XML1.0 compliant HTML file though I prefer using Cherrytree because of the collapsible navigation tree it automatically adds.

1. Change all the Document Settings you need before you start writing.
To avoid any frustrating global document changes midway, do all the customizations before you start writing. Everything from fonts, to indents, page size, default bullet symbols, and PDF export options are all available in the Document Settings window. Click Document and then Settings and make sure everything is set. Document Class is arguably the most important setting though in my case, I find TOC and numbering to be the most important configuration to edit particularly since my output is primarily PDF documents with a TOC.

2. Select and use images carefully.
Like Docbook, the quality of images inserted into LyX varies depending on the output. A high-quality PNG on a LyX document exported to PDFLateX looks blurred and small. However, it's huge and clear if you exported the manual to an HTML file and exporting to DVI in LyX is especially terrible for images. I find it useful to keep separate copies of the same LyX file for an HTML manual and PDF one.

3. Use Vertical Space and Page Breaks (no carriage returns!)
For WYSIWYG page layout applications like Scribus and InDesign, you just drag and place graphics and objects wherever you want, using guides to approximate distance and alignment. In LyX, you can't press the RETURN key to add space between paragraphs and inserted objects and images. Add Vertical Space by clicking Insert then Formatting. Click Vertical Space ... to adjust breathing room between objects. Add Page Breaks by clicking Page Break under the same Formatting menu. If you're having a tough time visualizing how a document would look like use the View (CTRL+R) regularly.

4. Don't change Environments if you can change Text Style - and vice versa
Environments such as Part, Section, and Itemize have a corresponding spacing and text style. Depending on the TOC and numbering preference for the document, it also affects the PDF TOC. Use the Standard Environment and click Edit and then Text Style if you just want to change the appearance of the text but don't want that text to appear on the TOC. Otherwise, use the correct Environment. It's helpful to click the Toggle Outline pane to get an idea how your document will appear on the TOC.

5. Save the .lyx file in one folder
Save the .lyx file in one folder so that whenever you export to DVI or HTML, everything appears in one place. It may seem like a no-brainer but LyX doesn't exactly give you a dialog box asking for the save destination when you export a document.

6. Insert Hyperlinks
If the eventual output is to PDF or HTML, use the Hyperlinks feature. Click Insert then Hyperlinks and select either URL, web, or File.

7. Use Box not Note
Note is very useful for just plain LyX documents but if the end result is PDF, use the Vertical Space, Box, and Indent to create the effect of Docbook-like Notes, Warnings, and Messages. Click Insert then Box and select the type of box you want to use for your text.

8. Looking for Size, Bold, and Italics?
Some users may get frustrated about changing standard text properties in LyX because options for different sizes, underline, and bold properties are found under the Edit menu. Click Text Style then Customized.

Continued in Tips on Writing a Manual or Guide using LyX Part 1


Popular posts from this blog

Quick Fix: MS Office Click to Run and CPU usage

Notes on UPnP/DLNA media streaming with Windows 10

Vivosmart HR: Setting up Notifications and Music Controls Part 1