Most of the documentation I work on these days is destined for online delivery, so it’s reasonable to expect users to be able to zoom in/out to display text at a size that suits them. They may even user browser settings to override baseline fonts and colours to ones that are preferable/more accessible to them. But when hardware documentation goes in-box with the product, the documentation and its contents become subject to physical dimension restrictions, and you need to make sure that the information fits and is legible.
A problem
While there may be a rough indication early on of potential physical restrictions on documentation size/format, this probably won’t be set in stone until close to delivery time, when manufacturing confirm what size box they’ll be using and how much space has been left for docs. A single A4 sheet can be folded to fit in most boxes, wrapped around the product if necessary. But once the documentation content starts to build (for example, adding legally mandated blurb, multilingual content, or crucial appendices), then it can be tricky to ensure the physical booklet fits the packaging. And it’s not as simple as scaling the text in line with the page size. An A4 sheet of 12pt text may be fine, but print the same content scaled to A6, and now your text is virtually illegible.
I experienced one panicked release where a page size of A6 was requested at the last minute. I was working with a MadCap Flare based project, generating PDF outputs, and sending those to the printers. We occasionally requested that an A4 PDF be printed at A5 size, and that was fine; but printing an A4 PDF at A6 size was going to make the text illegible.
(Aside: If you’re not familiar with Flare, it’s an excellent authoring tool, but project set up is not trivial – you compile your final output based on a set of HTML topics, plus TOCs, target definitions, page layouts, CSS, conditions, snippets, variables and more. Very powerful, but definitely not trivial to make a sudden swerve to publishing a new page size!)
A solution
For that pass, I decided the simplest solution was to continue with A4 page layouts, but to update the supporting CSS to include an A6 medium. For the A6 medium, I manually edited the font size for each style (headings, paragraphs, headers, footers, list items, cell contents, captions, …) to something that would be legible when my A4 output was printed to A6. The strategy worked, the booklet looked good, and everyone was happy with the result.
But, I was eager to avoid a similar panic in future. Post-release, I decided to spend some time rewriting the CSS so that print font sizes were defined relative to a base font size. Next time a new page size needed to be catered for, whether larger or smaller than A4, a one-line CSS edit would see all headings, table content, footnotes, etc. scale relative to that value. It was time well spent. Not only was the project ready for font resizing in response to different print size requirements, but it was additionally future-proofed against potential branding changes impacting font family or colours.
The very abbreviated stylesheet below demonstrates how using relative-sizing worked in MadCap Flare-compatible CSS. It includes very simple CSS customisations for a small number of supported tags: in practice, you could make endless customisations around padding/margins, boxes/rules, font, colours, etc., to make your content easier on the eye whether you go for on-screen or print outputs.
body {font-family: Arial;}
@media online{
body{
font-family: sans-serif, Arial, Calibri, Verdana;
font-size: 9pt;
}
}
@media A4{
body{
font-size: 10pt;
}
}
@media A6{
body{
font-size: 16pt;
}
}
p{
font-size: 100%;
}
h1{
font-weight: bold;
font-size: 180%;
page-break-after: avoid;
}
h2{
font-weight: bold;
font-size: 150%;
page-break-after: avoid;
}In this CSS, I’ve defined 3 possible media for Flare to use: online, A4 (print), and A6 (print).
- I’ve defined a catch-all base font for all body text: Arial. If Flare doesn’t see a medium-specific override, this is what it will use.
- I’ve customised the base font for each of my 3 media: online content will use a standard cascade of browser-compatible sans-serif font families, and a base size of 9pt; A4 will use the catch-all base font in 10pt; A6 will use the catch-all base font in 16pt (remember, I’ll generating an A4 PDF, which will be printed at quarter size).
- Finally, I’ve defined relative sizes for paragraph blocks, level 1 headings and level 2 headings: these are set to be percentage multiples of the base font, so I don’t need to set custom font sizes on a per-style basis for each medium.
Whether working with a tool such as Flare or not, it’s worth investing time in writing CSS that can be quickly and easily modified when changes are needed, since they always seem to be critical requirements at the most inopportune times! Simple fixes are removing redundancy (repeating the same font family declaration for every single tag) and building in well thought out dependencies (making font sizes relative); or you can go wild and use CSS variables, for example to set brand colour definitions (more here courtesy of w3.org, or here courtesy of Mozilla).
