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.
Continue reading “It’s all relative – CSS and MadCap Flare”Category: Tech Writing
How to manage a translation project when you don’t speak the language
As a tech writer, I’m sometimes called upon to manage documentation translation. While I can hold my own conversationally in a couple of second languages, I don’t speak the full range of target languages often required by many clients, so I have to trust my translators to do a good job. But not speaking the lingo isn’t a reason to treat the translation process as a black box. If you’re in charge of a translation project where you don’t speak the language, here are a few things you can do to facilitate the translation process, and validate what comes back.
Continue reading “How to manage a translation project when you don’t speak the language”Style Guides
Docs are (sad to say) often a point of last resort for a reader who’s already frustrated and cranky over failing to figure out the answer through trial and error, so any additional barriers to them getting at the information they need will not go down well. If more than one person writes your documentation, a style guide is a must to ensure that your end reader feels comfortable with and confident in your documentation. Continue reading “Style Guides”
Writing and Formatting Headings
Documentation users rely on headings to quickly locate content of interest, so they should be easily identifiable and provide meaningful context/keywords in a consistent way. Within these golden rules, though, there’s ample room for customisation to reinforce a particular document/provider’s brand. Continue reading “Writing and Formatting Headings”
Cyrillic characters in LaTeX
This one caused some headaches here, so recording the solution in case it’s useful to anyone else.
I wanted to include a Cyrillic string (copied and pasted from an email) in a LaTeX document whose default fonts didn’t support Cyrillic, but when I saved and compiled the file it was replaced by a string of question marks instead. After much poking around and experimentation, and with some assistance from Dave who is even more proficient in LaTeX than I, this solved it:
- First off, make sure you’re saving your document in UTF-8. (In WinEdt, this is set under Document > Document Settings… > Format.)
- In the document preamble, define the font family for cyrillicfont to one that matches your main package’s font (or that is close enough, but supports Cyrillic):
\usepackage[utf8]{inputenc}
\usepackage[T2A,T1]{fontenc}
\usepackage{polyglossia}
\setdefaultlanguage{english}
\setotherlanguages{russian}
\newfontfamily{\cyrillicfont}{Times New Roman} - In the document body, add your Cyrillic content in the second pair of curly brackets of:
\foreignlanguage{russian}{}