This post is for Dave over at WhatHeSaid.ca and YukonDude.com, because he asked.

I learned technical writing at Nortel Networks where I wrote customer information manuals for the DMS-100, the Passport 7K, and other documents for engineering teams (like AMA billing requirements and ISUP technical specifications).  The most important lessons I learned were:

• Know the product
• Know your audience
• Organize your information
• Know the English language

First, while I have your attention, I would just like to say that I think many (almost too many) organizations underestimate the value of documentation. Other than the product itself, documentation is the only part of the product a customer sees. It makes an impression–not only on your customers, but on your customer support team, your product test groups, any new employee, your marketing department, product management, and I’m sure there are more that I’m not thinking of right now.

I will refer to my first technical writing contract at Nortel as anecdotal evidence. Helen Borodalyuk hired me to address XXX line items in the product information suite for DMS-100 switch for NTT (a telecommunications service provider in Japan). They judged the quality of the code and the quality of the product based on the quality of the documentation. Something I still tend to do. I guess first impressions are lasting impressions.

Regardless, everybody benefits from having accurate, succinct, and complete documentation. I believe good product documentation makes a company scalable. Leading technology companies (Google, for example) also make great multimedia content. In today’s world, I believe good documentation is more than a PDF.

Anyway, I’ll get off my soapbox. Without further ado, here are a few more words on my lessons learned as a technical writer.

KNOW YOUR PRODUCT
Use your product you are documenting. Learn it inside out (engineering perspective) and document it from the outside in (user perspective). For example, if you were writing the procedures to install a telecommunications networking product. Find out how the product is shipped. Take it out of its packaging. Start putting it together. What do you do first? What do you next? What do you do after that? Document every step along the way.

Basically, learn by doing. Systematically document every action. Teach your user how to use the product. Determine what tasks they need to do to make the product work. Describe the task and document the procedures.

KNOW YOUR AUDIENCE

The purpose of technical writing is to teach your audience something about the product. Imagine your audience has a grade 8 level education.

If you have an audience who doesn’t speak English (or the language you are writing in), imagine that they might need a dictionary to translate or define words. Use Simplified English writing rules (below).

Know the main tasks of your audience. Know if they are marketing users or maintenance users. Know if they are technicians or trainers. Know exactly who your primary audience is. Write your documents as if you were talking directly to them.

ORGANIZE YOUR INFORMATION
There is a whole discipline around organizing information. Information architecture. Information design. The buzz word in the late 90s was “information mapping”. Whatever it is now, just know that you have to organize your information to present it in digestible pieces to your reader. My personal philosophy is: “Write so they don’t have to read what you have written.” I think that is a direct quote from Robert Horn. But basically, readers of user guides and manuals have a specific task in mind when they are looking at your information. Present your information so it makes it really easy for a reader to find exactly what they are looking for.

There is a lot of value in information architecture (done correctly). A valuable architect would be able to define the required information about the product for all audience types and be able to build a information framework (architecture, library, whatever you are going to call it). The right publishing system (and person) could dynamically produce predefined information depending the audience and their requirements. For example, you can use product descriptions in marketing collateral and in hardware guides. One piece of content: two audiences. I actually have an information model I developed specifically for telecommunications equipment. But I believe it would work for many products.

Also, do you know how a reader digests information? I have this formula: one third audio (or text), one third visual (pictures, diagrams), one third practical (engagement, procedures, and practical examples). Any one person prefers any two of those formats. If you present your information in all three formats, you will reach a greater audience AND a greater part of your audience will retain what you have documented. Use graphics or other media whenever and where ever possible.

That formula also translates to finding information on the web. On the internet, this world of accessible information, there is a rule: four clicks and the user should find the information they are looking for. The four-click rule also translates to product information suites and to user interface design regardless of the platform (computer software, mobile devices).

KNOW THE ENGLISH LANGUAGE

You are not a creative writer. You are a technical writer. There is a difference. Being a technical writer is a lot like being a journalist. Investigative reporting–actually. You are researching, investigating, interviewing, putting facts (systems, software, solutions) holistically together, and presenting digestible information.

One of my most powerful tool for technical writing is simplified English. According to Wikipedia: Simplified English is a subset of English grammatical rules that was developed by the aerospace industry and is now officially known as ASD-STE100 Simplified Technical English (STE).

Keep the simplified writing rules (below) in mind for every sentence you write. Check. Recheck. And check again.

SIMPLIFIED ENGLISH WRITING RULES AS I REMEMBER THEM

• Only use words that are in a dictionary and can be translated
• Use active voice
• Use present tense
• Create sentences with 21 words or less
• Create simple sentences: one noun, one verb
• Create short, visual paragraphs
• Use parallel lists
• Use positive statements
• Be gender neutral
• Avoid conditional tenses (could, should, would)
• Avoid slang and jargon
• Avoid gerunds at the beginning of sentences
• Create procedures with 10 primary steps or less

If you wanted to start somewhere with this Simplified English style, definitely check out  that standard. ASD-STE100 Simplified Technical English (STE). It takes practice and a good editor to become proficient. But it is definitely worth it.

Did that help you Dave? Was that the type of info you were looking for?  If  I didn’t bore you too much, here are a few more thoughts.

PROCEDURES
Procedures achieve tasks. Figure out what tasks your audience needs to achieve. Perform the tasks yourself. What do you do first? What do you do next? What do you do after that? What makes the most sense — from the user’s perspective?

Ideally, tasks shouldn’t be longer than 10 primary steps. Write sequential steps as separate sentences. Use a primary step to state the action. Use sub steps to describe specifically how to achieve the action.

Test your procedures. Ideally, have someone test them for you.

REFERENCE GUIDES

Reference documents provide dictionary-type information on any user-provisioned variable in the system. My formula for documenting reference manuals was:

• Name the parameter.
• Define the parameter. Where is it? What does it do? Why is it configurable? If it’s an operational parameter, why is it there?
• List the possible values in the parameter. Define each value. Document the purpose of the value and it’s effect on any other parameters in system. Describe the dependencies?

(If anything, documenting a reference guide is the single most exhaustive technical writing task I have ever done. But, in the end, I knew the system inside and out.

EDITORS

If you can afford one, editors are invaluable. Find a good one. Work with them. You will become a better writer.

STYLE GUIDES

If you can’t afford an editor AND if there is more than one writer for the product, agree on a style guide so you don’t have to argue about init caps in titles or what to do with a semi-colon. (My advice…ditch the semi colon. Use a period and a new sentence. You get 21 more words. . My bible has been the Chicago Manual of Style. It’s a complete and widely used reference for style. Sun Microsystems also put out a good style guide called: Read Me First.

MY BOOKSHELF

My bookshelf includes the following titles. I refer to them incessantly:

• Chicago Manual of Style, University of Chicago Press
• Read Me First, Sun Technical Publications
• Don’t Make Me Think, Steve Krug
• About Face, Alan Cooper
• User and Task Analysis for Interface Design, JoAnn T. Hackos PhD (Author), Janice C. Redish
• Information Architecture, Peter Morville and Louis Rosenfeld
• Communicating Design, Dan Brown
• more…

Anyway. That’s what I have today. If I think of anything else, I’ll let you know.

~~~~~~~~~~~~~~~~~~~~~~~

PS: I didn’t just work at Nortel. You can view an online version of my resume at 9068Creative.com.

Part of my first assignment of my journalism course: “What particular advice would you give a friend of yours who wished to become a freelance writer?”

Here is my response.

The first thing I would tell somebody who asked me for advice on becoming a freelance writer would be: Start. Just start. Start something. Start a blog. Start writing a bit every day. Start talking to editors. Start the creative process. Start keeping track of your ideas. Start making writing goals. Start by making SMART goals. Just start somewhere. But don’t give up your day job.

Structure your day. Get up. Get dressed. Have breakfast. Do some activity. Then start your working day. Don’t fall into a trap of never getting out of your house and talking only to your virtual, online friends.

Eat properly. Don’t snack. If you are working at home, make space for your office. Take breaks. Walk to the printer. Get a cup of tea. If you know your neighbours, have a 15 minute chat—just to get some perspective.

Find a community of writers or writer wannabes. If you can’t find one, start one. Participate in that community. Find inspiration for ideas. Give inspiration for ideas. Try out ideas. Share your work. Get feedback. It’s part of nurturing your growth as a writer, as a professional.

Read books on writing to become a better writer.  Every time you write something, read it out loud to hear your voice—to hear what you have written. Can you make it sound better? Can you cut out words? Can you use another word? A shorter, cleaner word? One that sounds less pretentious?

Read what you want to write. Surround yourself with quality publications. Study the language. Analyze the audience.  Up your ante by pushing your own limits on digesting information and articles out of your comfort zone.

Take pictures. Learn how to incorporate multimedia into your stories. Visit the archives of your favourite publications. Learn what was so you can better describe what is.

Ask questions. Never be afraid to ask questions.  Prepare for interviews. Ask hard questions. Ask light questions. Ask questions your reader would be afraid to ask, but probably wants to know the answer.  Be honest. Have integrity. Know where to draw the line. Know if a line needs to be drawn, but push the limits.

Read your favourite author out loud. Hear the rhythm of their words. Better yet, transcribe your favourite book (an activity I have yet to complete).

Be original. Be authentic.

And last but not least: Believe in yourself and persevere with your goals.

I made this jambalaya last night. I was looking for something low-cal and healthy. I found this recipe in an old cookbook I had (from when I was a vegetarian): Vegetarian Dinner in Minutes by Linda Gassenheimer. It was the first time I, personally, had cooked with cayenne pepper. It was just the right kind of spicy.

• 2 tablespoons (30 ml) oil
• 1/2 cup (125 ml) medium yellow onion, sliced
• 1/3 cup (80 ml)  flour
• 2 or 3 cloves of garlic, chopped
• 1 zucchini, sliced into medallions, then halved (the original recipe called for okra. I couldn’t find that in my local Migros. I’ll have a look in the market the next time I go.)
• 4 medium celery stalks, sliced
• 1 medium pepper, diced
• 1 cup (250 ml) uncooked long grain rice
• 1/2 teaspoon (2.5 ml) cayenne pepper
• 1/2 teaspoon (2.5 ml) freshly ground pepper
• 1/2 teaspoon (2.5 ml) dried thyme
• 3 cups (750 ml) vegetable broth
• 1/2 pound (250 g??) of prawns (The original recipe didn’t call for prawns (being vegetarian and all. I didn’t add the prawns last night, but I will when I make the recipe again).
• 2 ripe tomatoes
• 2 tablespoons (30 ml) red wine vinegar
• hot pepper sauce

Heat the oil in a large nonstick frying pan on medium heat. Add onions and saute for 30 seconds. Lower heat and stir in flour. Continue to saute 10 minutes, letting flour turn a light tan colour (do not let it turn black).

Add garlic, zucchini, celery, and diced pepper. Saute 5 minutes, until vegetables are starting to be soft. Stir in rice, cayenne pepper, black pepper, and thyme.

Add broth and stir well. Cover and simmer 15 minutes.

Stir in prawns and cook until the prawns turn pink.

Fold in tomatoes and vinegar.

Spoon onto plates, serve, and pass the hot sauce!

The book also gave some tips:

1. Start onions and flour. While they cook, prepare the other vegetables.
2. When the flour is ready, complete the jambalaya.
3. While jambalaya is cooking, make the romaine and orange salad.

~~~~~~~~~~
4 servings
461 calories per serving
27 percent calories from fat

I made jambalaya last night. I was supposed to make this salad, but it was just too late. I was tired. Here is the recipe anyway. It looks yummy!

• 1 head of romaine lettuce
• 1 medium orange

Dressing

• 2 teaspoons (10 ml) of vegetable broth
• 2 teaspoons (10 ml) of fresh orange juice
• 2 teaspoons (10 ml) of Dijon mustard
• 2 teaspoons(10 ml) olive or canola oil
• Salt and freshly ground black pepper to taste

Wash lettuce and tear into bite-size pieces.

Over a small bowl, remove orange peel, and cut into segments reserving as much juice as possible.

Cut segments in half and set aside. Whisk broth, 2 tablespoons of orangejuice, and the mustard together in a salad bowl. Whisk in oil. Add salt and pepper to taste.

Add lettuce and orange segments.

Toss.

Enjoy with the jambalaya–or whatever.

**Recipe directly from: Vegetarian Dinner in Minutes, by Linda Gassenheimer.

Now that the nice weather is here, we are looking for a table to put on the balcony–so we can eat outside when it’s warm. And, if we have friends over, we can entertain outside. I haven’t found anything I like enough to buy. I thought in the meantime, in between time, I could just fashion one with some planks and two lightweight sawhorses or something. It would be an easy, temporary solution.

If you put a table cloth over it, who’ll know the difference?

I go into Hornbach (a European version of the Home Depot) and I wander around in the lumber section. I don’t see anything that I’m looking for so I go up to the customer service and I ask: “Je cherche ….ummm….pour les pieds. Mais, pas les pieds. Les pieds en bois pour mettre le bois au-dessus et puis la coupee.” I motion a lot with my hands.

Approximately: “I am looking for feet. But not feet. Feet for putting a board across, and then cutting it. Feet of wood.”

The guy actually understood what I was asking for. “Oh. Un chevalet.”

Glad to have found the word, I repeat, “Oui, un chevalet.”

“Oui. On les a. Juste, demande a le monsieur la bas. Il sait ou ils sont.”  “Yes. We have those. Ask that monsieur over there. He knows.”

So I go over to the monsieur who is helping another customer. I wait. He acknowledges I’m waiting and finishes with his customer. When he is ready, he says, “Bonjour, comment je peux vous aider, madame?”  (Oh. I am a madame here!!!) “Hello, how can I help you?”

“Oui. Bonjour. Je cherche un chevalier. En bois, s’il vous plait.” “I am looking for a knight. A wooden one, preferably.”

He starts laughing. “Un chevalier? En bois?”  Now, I am  confused. “Madame, je serrai votre chevalier.  Je vais vous montrer nos chevalets.”“A wooden knight? Really? Madame, I will be your knight. And I’ll show you our chevalets.”

My sister sent me this quote in an email. I have to post it—if only to add to the All about my butt category!

With time, women gain weight because we accumulate so much information and wisdom in our heads that when there is no more room, it distributes out to the rest of our bodies.

So we aren’t heavy. We are enormously cultured, educated, and happy.

Beginning today, when I look at my butt in the mirror I will think: “Good grief, look how smart I am!”

Smart ass!

My friend has this blue shirt. She’s described it to me twice. Both times, after our discussion, I’ve wanted to go out and find one for myself.

She says it’s just a regular shirt that she bought at WorkWear World. I think she said it’s made from material like Helly Hansen long underwear. Long sleeves. It’s close fitting, but not so close that it shows everything (ladies, you know what I mean). And the neckline is just a regular neckline. It’s not a scoop neck or a v-neck. It leaves everything to the imagination. And it’s just the right colour too. It’s blue.

She says she feels good when she wears it. And she gets the right kind of compliments when she wears it. Not lewd or suggestive comments. Just, “Hey. That looks good on you.” It’s flattering.

Just the right size. Just the right colour. Just the right material. Just the right compliments.

How often do you find that?

On March 16th, I asked my readers what  I should write about while I was over here in Switzerland. I had a few ideas and a few of you pitched me some more in the comments.

I started thinking if I were going to be researching and writing about life in Switzerland, I might find some traditional publishing outlets and start pitching to editors-and maybe actually publish an article or two. (Yeah–in my dreams!!!)

I did a bit of research and I did find a few publication, but  I also found the London School of Journalism. They offer online courses.

I promptly signed up for the course: Freelance and Feature Writing. I now have some writing homework that I will be working on. Also,  I want to write a submission for What’s Up Yukon’s Foreign Correspondent contest and one for the WriteOn blog here in Switzerland.

I have to start somewhere. Right?

This weekend, we are going to Salzburg to visit the Queen. No. Wait. The Queen is in England. We aren’t going to England. We are going to Salzburg: a salty burg with an Austrian accent–ha! I’ll get a story or two from this weekend, for sure.

My sister read the recipe on turkey in spicy peanut sauce and knows how much I like peanut butter–with just peanuts. AND SHE SENT ME SOME!!!!!!!!!!

THANK YOU BIG SIS!

THANK YOU.

Have a look at this:

I had some on toast with slices of cucumber this morning.

PS: I still haven’t found any in Lausanne.

My first week here, Ludo’s mother gave me some Swiss schwag — to make sure I was well equipped to live in Switzerland. She gave us two espresso cups with the Swiss cross on them.

To equalize the national schwag in the apartment, I am now looking for the Canadian version of these cups.

Specifically, I am looking for a white cup with a red maple leaf. I think they would fit nicely.  Has anybody seen something like that?