Archive for Technical Writing

Latest image – September

I’m resolved to knowing everything there is to know about transparencies and gradients. Here’s the latest mandala—for the month of September.

July is about change

I’ve been speaking with a lot of people recently who’ve expressed how much change they’re going through these days. Maybe it’s the economy or the realization that the environmental chickens have finally come home to roost, but it does indeed seem like change is in the air.
For my 2010 Mandala a month, I’ve called July’s entry “Change”. Although a mandala is fairly static, the fascination I have with mandala’s is how they focus my mind. It’s like watching a fire. It’s mesmerizing.
By way of explanation, this mandala is based on the golden mean – that is, the number 1.61803399. There have been a lot of studies done into design in nature as well as asthetics that indicate this number prevails. For example the nautilus is based on it.

This isn’t a scholarly document, so I’m not going to go into details about how the golden mean (ratio) comes into play here, except that it does.

My first draft of turning this into a mandal was promising, but not really up to standard (my measurements were off for one thing).

The problem was that I couldn’t figure out how the circle came out of the square, so I decided to jetison the squares and look at circles instead. The core concept, still fitting with the nautilus (golden mean) ratio and placement resulted in the following:

I then replicated it four times, recoloured it, used that set angle at 45?, played with opacity, shading and voíla!

July - Change

Roman Antics

This is such a clever way of visualizing data creatively that I had to share it.

New Photoshop Skills

An intended consequence of taking the Kelby Photoshop seminar last week at the Vancouver Trade and Convention Centre was to pick up new skills. And learn new skills I have!

To the right is an example of my new skills with creating realistic reflections and luminosity in an object. Also, I’ve started using my WACOM pen with different brushes to create artistic layered effects.

In the space of three hours, I popped out four flashy images on this theme.

May Mandala

I just finished my May mandala. In 2010, I completed one mandala image a month for 12 months as a way to improve my Adobe Illustrator skills and just for sheer diversion. May’s mandala is based on the himalayan poppy, also known as Meconopsis betonicifolia. There’s a sky-blue simplicity about these poppies that I find inspiring.

See all my Mandalas in Facebook (one per month for 2010).

Style and Tone

Discussing Style and Tone in technical documentation in the technical writing field is usually a one-minute conversation that really doesn’t even address core issues. Usually, the conversation is about style guides or templates (which has nothing to do with style) and tone hardly even enters into it.

Here are some quick definitions:


Style is the cumulative effect of choices about words, their forms, and their arrangement in sentences. Style is not just a decoration but rather is a atter of substance. Style affects comprehesnion and a reader’s attitude toward the document.


Tone is the writer’s attitude toward the reader as well as the subject matter. It describes the writer’s relationship to the reader—colleague to colleague or teacher to student. Tone also describes one’s own persona. Persona is the mask you wear as a writer. Do you see yourself as an authority on a given subject or an explorer sharing your findings. That’s tone.

Planning and Ergonomics

In a collaborative environment with multiple teams, communication is critical. To illustrate this point, a picture is worth a thousand words, no?

Ten Characteristics of a Good Technical Editor

In no particular order,

  • Knows the difference between big picture and details
  • Advocates for the document’s audience
  • Exercises critical thinking
  • Knows the difference between copy editing and technical editing
  • Knows the difference between content and design
  • Maintains communication with clients and other stakeholders
  • Maintains style and tone of documents
  • Can distinguish technical jargon from effective writing
  • Edits according to established practices and style guides (i.e., is not arbritrary)
  • Works with writers and subject matter experts in a collaborative and respectful manner

Technical Writing Style

Last night, I taught one of my best technical writing style classes ever. It’s funny, but I was super nervous before the class—I must have known I was destined for greatest (or something). I think what made the class go so well was that there was a consistent flow from introduction to final farewell that built on the idea that in order to write good technical documentation, you need to understand your audience. I even tied in or foreshadowed themes that I know I’ll be teaching in the ensuing weeks.

The flow from after the break from the card game (barnga) to the presentation on discourse communities to the final humorous presentation of the Grand Central Station freeze worked really well. They get it and they had fun getting it.

Next week, I need to find a way to incorporate the graphic I made a while back lampooning everything that’s wrong with technical documentation:
Where academia meets bureacracy