Poetry and Prose of Information Developer’s Life


For me, to find a perfect profession has always seemed to be even more difficult than to choose a favorite book. Some jobs were like societies of free poets—creative, funny, extraordinary, but at the same time too crazy and unstable. Other professions that I’ve been choosing look as if they were created by Marcel Proust—before you become interested in it, you should read a thousand of pages, and overcome a routine and a desire to fall asleep. So, I was wandering as a Rimbaud’s drunken boat “in search of lost time” (and a place, certainly!), until I’ve accidentally found a new book with a very intriguing and promising title—Information Development. I must confess that when I’ve started discovering this book, I didn’t know the plot, the theme, and the main characters of it. But now, I’ve already read some chapters, and I can honestly tell you that this is a…

View original post 1,010 more words


A visit from St. Techwriter

Leading Technical Communication

santaApologies to Clement Moore

‘Twas the night before deadline and all through the lab
Not a snack was uneaten — not even a Nab.

The team all were frantic, likes bees in a hive —
In just a few hours the site would go live.

The software was bug-free — well, maybe not quite.
But mostly, we figured, it ought to work right.

The UI was kludgy, with widgets and stuff.
But our tech guys said ship it so that was enough.

The specs had been written, then roundly ignored.
To take time to read them no one could afford.

Ready or not, out the product would roll:
Just barely good enough, that was our goal.

When down by the break room arose such a clatter,
I sprang from my bench to see what was the matter.

Away to the window I flew, scared to death:
Gazed into…

View original post 270 more words

How to use custom fonts in TopNav help


Imagine a situation: you’re going to prepare a help system for a website. You suggest creating a help that has the look and feel of the website itself. The customer is happy with that, and you’re eager to start as you have MadCap Flare 11 or 12 with that cool TopNav output. However, the website uses custom fonts, and you need to use them in your help system.

What would you do?

View original post 765 more words

Noises in manuals

CyberText Newsletter

I purchased a new freezer this week. One of the first things I do when I get a new appliance is read the instruction manual. Yes, I know that only about 10% of the population reads an instruction manual, but I consider it a way to learn about the product AND a professional courtesy I extend to all those fellow technical writers who write them.

What made this manual different? It has a ‘noises’ table! After reading it, I think ALL appliance manuals should have one of these, if the appliance makes various noises during its operation. I know that products like UPSs have info on the various beeps and alarms, but this table listed the normal operating noises the freezer makes. So simple, and just brilliant.


View original post

What Do You Need to Survive the 21st Century Workplace?

Heroic Technical Writing: Advice and Insights on the Business of Technical Communication

This topic was inspired by an online video chat by Claudio Fernández-Aráoz, hosted on the Harvard Business Review’s Facebook page. I didn’t watch the whole thing, but he raised some interesting points. Aráoz shared a combination of traits that he thought would would be useful for staying employed in the future. These included:

  • Curiosity
  • Insight
  • Engagement
  • Determination
  • Emotional intelligence
  • Strong delivery
  • An ability to sell your skills
  • Being proactive

Curiosity is a good one because it’s a spur to keep learning about whatever you’re working on or whatever’s happening in the industry where you work. Insight can include seeing your work in a unique way and sharing what you know with others. Engagement of course means that you’re interacting often with your leaders, peers, subordinates, or customers regarding the work you’re doing. Determination comes up whenever you need to get your current work done or have to find the next role–you need…

View original post 482 more words

Standard Technical English (STE) Rules According to Star Wars

This is truly amazing!

Write Spot

A few months ago I wrote an introduction to Standard Technical English (STE). Check it out if you want to get a better idea of the history, uses, and benefits of STE.

The following article is a visually representation of the STE rules using Star Wars. I also included a high-level explaination of each rule.

  • Use STE approved words.
  • Make sure that you only use the approved forms of verbs and adjectives shown in the STE dictionary.
  • It is okay to use Technical Names not listed in the dictionary. Only use the Technical Name as a noun or adjective, never as a verb. If possible shorten Technical Names. However make sure that you are not using jargon or slang.
  • Be consistent. Once you decide on what to call something then continue to use that name and spelling.
  • Avoid abstractions. Meaning, use word that are specific. Do not leave the…

View original post 1,100 more words

Which Graphic Should You Use?

Heroic Technical Writing: Advice and Insights on the Business of Technical Communication

Data visualization is something they really should teach in high school–or maybe earlier–because we receive a lot of numerical information visually these days. This essay is a brief introduction to the topic.

Tables and charts are a relatively new tool for visually depicting numerical information. You could go back to Rene Descartes, who created the Cartesian (x-y) coordinate system in the early 1600s for graphing points, lines, and conic-section curves. The perpendicular axes have Western conventions for determining numerical values: specifically, points on the coordinate system increase in value from left to right and from bottom to top (ascending/increasing in value the closer up you get to pointing toward Heaven).

Moving ahead nearly 200 years, we encounter English clergyman Joseph Priestly and Scottish economist named William Playfair, who started the first concerted effort to make economic and other forms of information understandable to the general public. Priestly developed the timeline chart to depict overlapping…

View original post 1,046 more words

Why Being Different is Better than Better

Heroic Technical Writing: Advice and Insights on the Business of Technical Communication

Sorry, I’m a Generation Xer, so the death of the musician/composer/singer/director/actor Prince cannot pass unnoticed. If this seems like an odd topic to bring into a technical writing blog, bear with me, I’ll get there.

There are individuals out there in the workforce who are good or excellent at a few things: awesome editors, wittycopy writers, creative storytellers, wise and understanding managers of people, etc., but that doesn’t mean they’re good at allof those.Others might be in the same line of business, but these prodigies are justbetter, through sheer talent and a ton of effort and are able to show a career of high-quality, impressive work.I envy those people. When I was younger and more arrogant, I related more to Mozart than Salieri; as I’ve gotten older, I’ve realized that I’m closer to F. Murray Abraham’s cranky “mediocrity.” It’s not that Salieri was a bad composer, he was…

View original post 525 more words

7 Tips for Better Documentation

Write Spot

Basic writing skills are not something that should be taken for granted. Time and time again, I read poorly written manuals, instructions, and articles. Whether you write for a living or it is simply an annoying add-on to your real job, it is your responsibility to effectively communicate through the written word. If you do not understand basic writing best practices, you will fail.

Here’s an infographic with 7 tips for better documentation:


View original post