It’s all relative – CSS and MadCap Flare

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”

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”

Is this email spam?

I get a lot of spam. In some cases, I’ve provided an address to a site/service I genuinely want to use, and not been careful about opting out of their helpful add-on email offerings. In some cases, my address has been scraped or guessed by someone who doesn’t give two hoots about my email preferences.

Replying or clicking unsubscribe can be a bad idea if you get a one-off piece of spam, as it verifies to the sender that the scraped/guessed address is live: this may result in your address being prioritised in future campaigns, and potentially shared with or sold to other spammers. The safest approach in this case is to delete the mail without clicking any links. If you get repeat messages from the same source, or in the same style, either blacklist the address, or set up keyword-based filtering to avoid seeing the same kinds of mail in your inbox again. Check your mail client’s documentation for information on how to do this. If you’re getting unwanted messages from a legit service you really did subscribe to, feel free to click the “unsubscribe” or “mail preferences” link in their signature and change the categories/frequency of the messages they send you.

Continue reading “Is this email spam?”

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”

As simple as possible…

Over-simplification is an issue that bothers me. I sometimes need SMEs to explain a new field/concept to me in excruciating detail so that I understand it well enough to start writing about it, but I don’t always include the same level of detail in what I write, because I know/expect that the intended audience is starting from a greater level of understanding than I did.

Wikiquote suggests that “Make things as simple as possible, but not simpler”, a quote popularly attributed to Einstein, is itself a simplification of “It can scarcely be denied that the supreme goal of all theory is to make the irreducible basic elements as simple and as few as possible without having to surrender the adequate representation of a single datum of experience.”

The simplified version may be snappier and more user-friendly for most of us today, but the original, which appears in Einstein’s 1933 Herbert Spencer Lecture “On the Method of Theoretical Physics”, was simple enough for the intended audience. And that’s kind of the point.

Continue reading “As simple as possible…”