It feels like I have almost reached feature completion with my Packt Publishing backend. It does just about anything I need. In fact, I don’t really think about editing my generating ODT files. (The only thing is potentially moving the [[layout notes]] that don’t properly wrap).

Sure there are lots of other styles, like bullet-within-tips, and code-following-bullets, but I don’t really use those. In fact, it’s probably a good thing to avoid those highly specialized spacings. I have paragraph formatting, section headers, URLs, code blocks, bullet lists, tables, and now numbered lists.

As usual, it took a bit of digging to figure out EXACTLY how this works in ODT’s cryptic XML. Sometimes, I have to manually edit the ODT file and inspect it afterwards to see what changed. But thanks to a bunch of digging using vi, TextMate, and other things, I deduced what the missing style bits I needed to add to packt.conf.

Suffice it to say, I now have it tagging numbered lists, which are important for a sequence of steps. In this chapter, we create a tiny app that lets you look up issues across multiple GitHub repositories, and display them in both a desktop web page as well as a mobile web page. The sequence of steps to get a personal access token didn’t really fit a bullet list, but instead needed to be written up in order.

When I write such detailed step-by-step instructions, it just isn’t suitable in a paragraph or a table. By putting this in a numbered list, the reader can quickly spot the chain of steps, and if he or she is already familiar with the concept, easily skim past it to the next juicy bit of code.

A key tactic in writing is to break up all the material into easily consumable chunks. Several sub-sections, along with a few paragraphs between code blocks is a start. Calling out key parts of a code listing with either bullets or a table provides a nice, easy-to-view way to understand things. And if you already know what the code block says, your eyes will easily move past such a listing onto the next paragraph.

Happy reading!