STC Toronto Chapter Newsletter

Grammar checkers: StyleWriter

noreply@blogger.com (Mona Albano) — Sun, 03 Aug 2008 02:20:00 +0000

This looks like a fascinating product! StyleWriter is a sophisticated grammar checker that looks at your writing and gives a many-dimensioned diagnostic:

Words: 93
StyleWriter suggested improvements 17:
· 6 wordy phrases
· 2 complex words
· 3 business clichés
· 5 passive verbs
· 1 long sentence
· 1 grammar error (by yourself)
· 1 hyphenation error (follow-up)

Thank you

noreply@blogger.com (Veronica Kutt - Front Runner) — Fri, 01 Aug 2008 15:03:00 +0000

To the Administrative, Community Councils, and Membership,

Thank you for awarding Front Runner Training for our long-standing support of the STC Toronto Chapter. We are happy to accept the recognition and display the plaque.
We look forward to continuing our successful relationship with the STC.

Sincerely,
Veronica Kütt
President
Front Runner Training, a Div. of Front Runner Publishing Solutions Inc.
416-515-0155
Call Toll free: 1-877-999-0155
veronica@front-runner.com
www.front-runner.com
"Learn what you wish you'd known yesterday!"®

Shlomo Perets workshops in Toronto!

noreply@blogger.com (Veronica Kutt - Front Runner) — Fri, 01 Aug 2008 14:57:00 +0000

Front Runner Training is hosting Shlomo Perets in Toronto to deliver his highly sought after FrameMaker to Acrobat Advanced Techniques workshop and two Advanced Acrobat workshops!

Bring your laptops, bring your files, bring your questions!

FrameMaker to Acrobat Advanced Techniques
Monday September 22nd & Tuesday September 23rd

$1,240.00 (General public)

Designing Access to Information & Testing Your PDFs

Wednesday September 24th

$540.00 (General public)

Creating PDF Forms

http://www.front-runner.com/training/outlines/workshops/Acrobat_forms.html

$540.00 (General Public)

9 a.m. until 5 p.m. each day
Continental breakfast included

Take advantage of our Early Bird Special for STC Members Only - until August 15th, 2008
SAVE $150.00 on the FrameMaker to Acrobat course and lower the fee to $1,090.00 per person, plus GST.
After August 15th, the fee for STC Members is $1,140.00 per person, plus GST Payment and STC # (if applicable) required at time of registration.

Save $75 on the Designing Access to Information & Testing Your PDFs and Creating PDF Forms and lower the fee to $465.00 per workshop, per person, plus GST.
After August 15th, the fee for STC Members is $490.00 per workshop, per person, plus GST

These discounts cannot be combined or offered with any other promotion or discounts.

Please contact Front Runner to register for your workshop.

Sincerely,
Veronica Kutt
President
Front Runner Training
A Division of Front Runner Publishing Solutions Inc.
416-515-0155
Call Toll free: 1-877-999-0155
veronica@front-runner.com

Labels and other dogs

noreply@blogger.com (Andrew Brooke) — Thu, 03 Jul 2008 18:41:00 +0000

Here I am, in my basement, surrounded by mountains of dog food I'm desperately trying to organize. We own one dog, an odd-looking labradoodle named Jessie, however, my brother-in-law's dog Gracie often visits. Both dogs need feeding, therefore I own two large plastic containers filled with food for each dog, and both dog food types look almost identical. I wonder: What is the best way to label each container?

The obvious labels would be Jessie and Gracie, however I often get the dogs' names mixed up even when I'm around them; Jessie and Gracie simply sound too similar, and the dogs themselves do not carry signs that clearly identify them. I decide on the labels Our dog and David's dog, eliminating all confusion.

Labels are everywhere in documentation, specifically in:

the name of a document: User Guide, Admin Guide, Install Guide, and so on
chapter names
heading titles

These are all critical identifiers, and just like the dog food box labels, they need to be clear, descriptive, as short as possible, and leave no room for confusion.

As an example, our company used to create Installation Guides, but this was not descriptive enough because it did not distinguish between guides for users who were installing our software for the first time, and guides for users who were upgrading an existing version. We therefore changed the document titles to:

Guide for New Installations
Upgrade Guide

Chapter titles and headings also need to be clear and unambiguous. Documents is vague, Creating Documents is better, and Creating Documents on a Database may be better still, especially if you need to distinguish between this topic and creating documents in another location.

Labels are also in software in the form of fields, menus and title bars. Experienced technical communicators provide valuable feedback and insight for the naming of these items. As with documentation labels, software labels need to be clear, consistent and leave no room for confusion. I'll share an interesting example.

I was working with a developer on a complex database administration application. One of the functions the user could do was rerun a query by clicking a button labeled, appropriately enough, Rerun query. The developer said the problem was that there were many different queries that the user could run, and that they needed a quick way to know which one they had run before re-running it. I asked if was possible to embed the name of the query that had just run into the button name, so that, for example, if the user had run the Last Name query, the button label would be Rerun Last Name query?

I remember the developer's eyes widening and his face lighting up as recognized the elegant beauty of this solution. "Yes," he said, "it can be done!"

More exotic things I have be asked to label include database tables, attributes and elements. It can be very challenging, and very rewarding to give these things the right name, one that nearly sums up the essence of what the thing is. So choose your labels carefully - they can turn good documentation into great.

Now excuse me while I go feed the dogs...

Beta-test the TTC's new Web site

noreply@blogger.com (Mona Albano) — Tue, 10 Jun 2008 15:34:00 +0000

The Toronto Transit Commission's new Web site is in beta test, which means it's not in production but we can visit it and the TTC wants our feedback to finalize the design. You'll be doing yourself and myriads of TTC users a favour.

The Toronto Star reports that the TTC's new home page is still a work in progress:

—Tess Kalinowski, Transportation Reporter
Now there's a better way to navigate the TTC online but the transit agency isn't home yet when it comes to its new website. The TTC previewed its long-awaited homepage today to replace the version it's been running since 1998. With new easy-to-read graphics and search engines for bus and streetcar routes, it nevertheless doesn't yet have a trip planning tool or up-to-the-minute service updates for the system. Those features, along with an e-commerce function, will be added by next year, said the TTC's marketing manager Alice Smith. Eventually the TTC's site will function like the Chicago transit system's where users can actually watch the buses and see delays, said commission chair Adam Giambrone.

A quick look at the old site

This is the TTC's old home page. It's quite long. Notice the link at the top to the new site.

The badges in the old page are links to sub-pages. Those might be in the TTC's own Web site. This is the result of clicking "TTC Service:"

Or they might go to a page in the extensive City of Toronto Web site:

The new site

The new site has an introduction. It uses a lot of abstract nouns and needs a plain-language rewrite.

Then you click "Continue" to get to the new home page:

This new web page is quite wide, about 960 pixels. People with older monitors might not realize that there's a far right-hand column with more choices unless they have horizontal scrolling turned on and they look at the horizontal scroll bar.

The new site looks pretty. It uses the streetcars' colours of red, black, and white. But close your eyes half-way and squint at the screen. You'll see that the heavy black bar across the top is the strongest visual element. It pulls your eye away from the more important text below.

Because of the strong horizontal elements, It took me a while to realize that the menus should be read vertically from the heading above the line.

Four topic areas are headed by a red line faintly divided by grey bars, and with a dot like a station on a route map. To me, the dot separated the menus from their title rather than connecting them.

The site is divided logically into four main topic areas

Schedules & Maps
Fares & Passes
Riding the TTC
Service Alerts

This is the Schedules & Maps area.

It was not obvious to me that the three symbols along the top stand for the three kinds of routes. Perhaps the symbols could be placed vertically with their descriptions beside them. Also, there's lots of room to write "Rapid Transit" or "Rail Transit" instead of the cryptic "RT." When in doubt, spell it out.

There's a place-holder for a link to the future trip planner. I hope that it will allow you to say when you want to arrive will tell you when you have to leave, instead of just asking you when you want to leave. Or perhaps it will even ask you which kind of planning to use.

To get to a schedule, click in one of Subways, Buses, or Streetcars. If you know your route number, such as 501C, you can type it instead of searching through the schedule menus.

I chose Streetcar Routes. You go to a second-level menu of major routes.

Select a route. (I chose 501 Queen.) The white-on-black text at the top of the route tells you that this is for eastbound streetcars. Many people can't read reverse video easily and will read "Westbound" more clearly than "Eastbound."

The schedules have the very nice feature of showing the next vehicle scheduled to go by in each direction. (In future, you may see real-time results.) The next scheduled arrivals appear at main intersections for active routes.

If you select a sub-route, you get a more detailed schedule:

Unlike the Streetcars menu, the Service Alerts menu is scattered over the page:

The Service Alerts menu makes your eye rove around to see all the choices. This seems like an attempt to use up all that horizontal white space. There's nothing wrong with the old, vertical format:

If drill down a level in the new Web site, you'll find that warnings such as Construction Projects are unfinished.

Until the Web pages are are complete, I think that they should link to the updates on the City of Toronto site, as the old Web site does.

The Star is correct: it's a work in progress. Take time to visit the new site and leave your feedback. We can help the TTC to improve their user experience if we act now.

First, go and roam around the TTC beta site. Then return to its home page. At the bottom is a link to a survey. Follow the link and fill out the survey.

Putting out fire with (pricey) gasoline

noreply@blogger.com (Andrew Brooke) — Wed, 04 Jun 2008 14:20:00 +0000

It's not a fun time to be a driver, especially if your car is anything larger than a phone booth. Gas is now almost $1.30 a litre. Creative thieves don't even bother trying to pry open locked gas caps - they simply get underneath your car, drill a hole in the gas tank and collect the liquid gold. Be glad you're not living in Britain, where the price per litre is an astonishing $2.40, almost double what we pay here.

The really sad part is that the price increases will continue. Within a few years, we'll match and then exceed Britain's current prices, and wax nostalgic over the days of $1.40 "cheap" gas. Can anything good come of this?

Hummers for sale

Yes, and it already has. People are forgoing their trucks, SUVs, minivans and other gas-guzzlers in favour of smaller cars. They are carpooling, taking public transit, and thinking twice before driving unnecessarily. High gas prices have become a de facto carbon tax, without all the messy legislation required. They are forcing people to be more environmentally responsible, and as Martha Stewart would say, "that's a good thing". High prices will no doubt accelerate the development and acceptance of fully electric cars. In other words, high gas prices are completely changing both society and industry.

Finger lickin' docs

Corporate change as a result of external factors and customer demand is nothing new. Recently, Kentucky Fried Chicken (KFC) announced changes that would make it more "animal friendly", as a result of pressure from the animal rights group PETA. (Veggie chicken burger, anyone?) KFC didn't do this out of the goodness of their heart - do you really think they care about chickens? KFC, like all corporations, cares about one thing - profits. And their profits have been dropping steadily as people try to eat more healthily. The last thing they needed was further criticism, so they gave in to PETA's demands.

A similar sea change is happening with documentation, but it will accelerate only when, as with gas, the price of the status quo becomes too high. For too long, companies have gotten away with creating documentation in an inefficient, unstructured format. They've been able to do this because they could afford to do it, but soon they won't be.

The ultimate 'change order'

The changes are already happening. The first companies to change were the ones where the documentation is translated into other languages. Translation costs are extremely high, but in an XML-based content management system, only the specific sections of text that have changed need to be translated. If a text segment is reused, so is its translation. The savings can be astronomical.

Companies with large volumes of documentation, often with different versions, also are changing to the new ways. Development time for new manuals will be shortened from months to weeks, or even days.

After all these international and larger companies have changed, the others will follow. They simply will not be able to compete otherwise.

Organizations have converted their documentation to the new format are reaping the rewards. Organizations that resist this change, that deny it's happening or that continually stall will end up in the same place as General Motors and Ford. Their documentation will explode more violently than a hundred litres of that pricey gasoline.

Southwestern Ontario Chapter Movie Night!

noreply@blogger.com (Andrew Brooke) — Thu, 29 May 2008 14:20:00 +0000

Everyone loves a movie night - especially a free one! To end the STC-SOC general meetings on a fun note (although you still can learn), they have decided to offer you the movie Helvetica.

Helvetica, a documentary film by Gary Hustwit, is about typography, graphic design and global visual culture. It looks at the proliferation of one typeface (which celebrated its 50th birthday in 2007) and how it and other types affect our lives. The film explores urban spaces in major cities and the type that inhabits them. It also contains discussions with renowned designers about their work, the creative process, and the choices and aesthetics behind their use of type.

When: Tuesday, June 3 from 6:00 until 8:30 (movie starts at 7:00).
Where: Princess Twin Cinema, King St., Waterloo
Registration: Please register with Ted Edwins, STC-SOC Public Relations Manager, by May 30 at noon.
Food: You can purchase food before the movie. Come early to make your purchases and to spend some time networking.

You can see more details about the movie and about registering to see it.

Questions?
Contact either Ted pr@stc-soc.org (STC-SOC Public Relations Manager) or Debbie Kerr president@stc-soc.org.

The council of the Southwestern Ontario Chapter looks forward to seeing you there!

Debbie Kerr
President
Southwestern Ontario Chapter STC

Simple & free screen-capture software

noreply@blogger.com (Mona Albano) — Fri, 23 May 2008 18:35:00 +0000

As a technical writer, I often have to take screen captures or "screen shots" to illustrate a software application or system. A convenient and perfectly adequate tool for the job is the freeware program ScreenHunter from WisdomSoft. It's currently up to version 5. If you're willing to pay, you can have a much more versatile version.

Thanks to STC member Ed Beliczynski of ExtendMedia, Inc., who originally recommended ScreenHunter to me and who is a fount of information on low-cost software tools.

Documenting Brenda Martin

noreply@blogger.com (Andrew Brooke) — Wed, 14 May 2008 16:55:00 +0000

The saga of Brenda Martin has finally drawn to a close, for now. Imprisoned in Mexico for over two years in deplorable conditions, found guilty only in the last week of her imprisonment, she was transferred to a Canadian village prison, then quickly paroled. In an interview, she said she'd like to start her catering business again. I doubt Mexican food is on the menu.

Death by docs

There were two documents that destroyed Martin. The first was the indictment written by the prosecution, alleging she was guilty of money laundering. The second was the written verdict from the judge who found her guilty. Martin has claimed that portions of the second document were simply "cut and pasted" from the first. This is what’s known as “single-source justice”.

In addition to these two, there was other documentation that prolonged the agony after she was found guilty. The first was all the paperwork that had to be completed by Corrections Canada to arrange her transfer to a Canadian prison. This may have delayed her release a week. (Couldn't they have transferred her and then filled out the forms?) Once in a Canadian prison, under much better conditions, more documentation had to be completed to arrange her parole. Still, as documentation deadlines go, these projects were completed relatively quickly.

I'm not opinionated - just always right

There was a huge variety of opinions on this case, ranging from "she's innocent, let her out," to "she's guilty, let her rot." It seems likely that she was an innocent victim, who, at worst, showed poor judgment remaining in a foreign country that has a notorious justice system, after her boss was convicted of a major crime, and without a work permit. However, the hard truth is that none of us outside observers know for certain if she was guilty or not. We don't have all the information, only selected bits of it.

Ignorance ≠ bliss

Ignorance of the facts is one of the main causes of poor documentation. How often do we document something, or rely on others to supply us information for our docs, without investigating and testing it for ourselves? Thinking you know something is not the same as actually knowing it. Trusting is ideal; verification is the real deal.

Squeaky Gonzales

One point many people raised is that Martin was one of hundreds of Canadians trapped in foreign jails. Why did she get special treatment? Simply, it was her pure, visceral, and extremely emotional pleas for help that ensured she would be speedily rescued. The squeaky wheel gets liberated, and the squeaky workers get their way.

All companies have limited time, money, and resources. The job that gets done, including documentation, is the one where the "squeakers" push it though. The best documentation is created by the squeaky writers - the ones that push, plead, prod, persuade, probe, and pester until they get the tools and time they need to do their job and the answers they need to create great documentation.

A brief word on briefs

I've a feeling we'll be seeing more “Brenda Martin” documentation soon, specifically the legal brief her lawyer will file if she decides to sue the Canadian government for failing to help her sooner. She may also decide to appeal her conviction to the necessary legal body, although it's not entirely clear who that would be. Is there a World Court of Appeal?

If she does make either of these legal challenges, it raises an obvious question: what's the point? She's out of prison now, so why expend time, energy, and money to sue the government or clear her name?

Of the two legal challenges, clearing her name might be the more justifiable. She is a convicted criminal. If she truly is innocent, you could see why she would want the conviction expunged from her record. Convicted criminals have a tough time getting a job, however, most potential employers and clients would be quite sympathetic toward her. It’s doubtful the "criminal" lable would have any real effect.

As for suing the Canadian government because they didn't help her sooner, this could easily turn public opinion against her (there was already a "Brenda backlash" while her case was dragging on) as people simply perceive her as a gold-digger. I'm sure she could make plenty of money documenting her story into a book, which of course she could sell the movie rights to. It'll be a great CBC movie of the week.

Justify my docs

Just as it's fair game to ask what the ultimate purpose of these legal actions is, it's also fair game to be continually asking what the ultimate purpose of your documentation is. If you cannot justify the presence of certain text or sections in your document, then you must change or remove them. And if you cannot justify the entire document, it must be thrown on the scrapheap of all dead documents.

Ultimately, we and our work are all judged. This is especially true during a job interview. Are you ready to face the court?

Learn about the power of podcasts on May 13

noreply@blogger.com (Mona Albano) — Sat, 10 May 2008 23:57:00 +0000

Podcasts are seen as a platform for reviews, opinions, and polemic. But they can do much more. This presentation helps you discover how valuable podcasts can be.

Podcasts are the next step beyond blogging. But they are also a powerful platform for training and user assistance. They are useful whether you're a technical writer explaining how an application works or a marketer expounding on product benefits.

Aaron Davis and Scott Nesbitt will examine how you can tap into the power of podcasts. First, they'll explain what podcasts are and how to create one.

You'll learn how podcasts

Can help maintain an ongoing dialogue about a domain or topic

Are a great way to disseminate new developments

Serve the users's convenience by being available anytime, and anywhere

Make supplementary material more interesting

Aaron and Scott will

Outline the mechanics of podcasting

Point out some of the popular training and educational podcasts on the Web

Analyze why these podcasts are successful

Tell how you can use the same techniques with your audio materials

About the presenters: Aaron Davis and Scott Nesbitt are partners in DMN Communications, a technical communications consultancy in Toronto. Since 2006, their podcast, Communications from DMN, has been entertaining, informing, and occasionally annoying a diverse global audience.

The meeting will be held in the Burgundy Room at the North York Memorial Hall, 5110 Yonge Street, concourse level, at 7:00 p.m. General Admission is $5; STC Members attend for free.
For directions, visit STC Toronto and click on "Meetings."

(This was based on the meeting announcement on the STC Toronto web site.)

Workshop on user experience design of web site information architectures

noreply@blogger.com (Andrew Brooke) — Thu, 08 May 2008 17:32:00 +0000

ToRCHI, the Toronto chapter of ACM SIGCHI, is organizing a one-day workshop on the topic of user experience (UX) design of web site information architectures (IA).

This workshop examines the design of web site organization and information architecture with a focus on user experience and usability considerations. Workshop activities will consist largely of analyzing and critiquing existing sites, discussing underlying design principles and guidelines, and completing design exercises and critiquing the results.

For complete information, view the workshop details.

The Ten Plagues of Technical Communication

noreply@blogger.com (Andrew Brooke) — Thu, 17 Apr 2008 21:21:00 +0000

This time of year, my family, along with many others, will gather to celebrate the festival of Passover. This holiday, like all Jewish holidays, can be summed up as: "There was a battle, we won, let's eat."

During Passover, we celebrate the liberation of our ancestors from slavery in Egypt. Lest you think slavery is an outdated idea in our so-called modern, free world, simply look at how many people are slaves to their cell phones, Blackberries, to their computers and cars, and to all their other material possessions. The things they own end up owning them. That's why Passover is one of the most popular and well-celebrated holidays, because the concepts of freedom and slavery are still relevant today.

One of the more colourful segments of the Passover story is the ten plagues brought down upon Egypt. Just as freedom and slavery still exist today, so do plagues. The ones faced by technical communicators are not quite as harsh as blood, pests and wild beasts, but can still cause us great pain.

Here, then, are the modern plagues that technical communicators face today:

1. Difficult reviewers - We've all experienced these. Reviewers who don't return drafts, or return them with such helpful comments as 'What?', 'Needs work', 'No!' or my personal favourite 'Huh?' Reviewers like this need to be placed in front of a firing squad for life.

2. Poor documentation software - Although great improvements have been made over the years, the software for creating documentation is still as not as good as it could be. Microsoft Word is the after-thought of a documentation tool. FrameMaker is quite solid, but still has many annoying quirks. In general, there are few tools, if any, that do everything we want at a reasonable price. We've come a long way, baby, but there's still so much further we could go.

3. Developers - Developers are like dentists - they're not really appreciated, they cause us great pain, but we need them. They are technically brilliant, somewhat autistic individuals whose greatest strength and weakness is that they focus on the two M's: mechanics and minutiae. That's why developers usually make bad tech writers. If you've ever had the misfortune of reading something written by developer, you'll know what I mean. It can only be described as "mutant documentation."

The problem is that developers have trouble standing back and seeing the big picture, and that's where we come in. We sift through the details and extract exactly what the end user really needs to know.

Also, some of the most challenging documentation is that aimed at developers - SDKs, APIs, Technical Guides, Data Dictionaries, and so on. Because it can be very dry and tedious to work on these, the pay is often quite good; you just have to be comfortable writing for Martians.

4. Marketers - The creature who is the polar opposite of the technical writer is not the developer, but the Marketer. Technical writers like to use as few words as possible, and ones that are simple and clear, with no fluff. Marketers, by contrast, like to use many words, often long, unclear, fluffy ones, to overwhelm the reader. Marketers love words and phrases such as: synergize, leverage, empower, paradigm, extreme quality, customer-focused, customer-obsessed, customer-driven, and so on, ad infinitum and ad nauseam.

There is marketing writing, and there is technical writing, and never the 'twain shall meet.

5. Billboard designers - Although you could lump these specimens with marketers, they are so particularly evil that they must be singled out. Like user guides, billboards are a form of communication designed to quickly impart information. However, many are so poorly designed, I wonder how their designers make a living. The type is far too small or has such poor contrast that it's almost impossible to read. The sad thing is that companies pay tens of thousands of dollars for this illegible junk.

6. Missing or bad indices - An index is one of the most important elements in any document. Users often turn first to an index to quickly find the information they need, often under stress. A user guide or online help is often only as good as its index. Therefore, good indexing skills are critical. Unfortunately, many writers neglect this important stage. They either fail to include an index, or include a skimpy or confusing one. Put yourself in the reader's place: wouldn't you want to be able to quickly find what you're looking for?

7. Duped docs - Duplicated text is the bane of my existence. I've spent more time trying to merge, conditionalize and normalize duplicate copies and versions of text than I care to remember. In one project, I merged twelve Word installation guides into one single-sourced FrameMaker document. It was pure pain, but it sure looks good on a resume.

8. Bad software - A strange and deadly belief has developed that if the software you're documenting is poorly designed, somehow the documentation will magically fix it. To the deluded who hold this belief, I ask: would you drive a car that had faulty brakes if the user guide warned you they were faulty? Of course not. Still, we don't want the software to be too easy to use, because then users wouldn't need any documentation!

9. Outdated documentation - It's out there, and we've all seen it. The docs that haven't been looked at or reviewed in years, possibly decades. You know it's a bad sign when you have to travel down into the cold, dark, bowels of your building to try to resuscitate old printouts. Here's one segment from an old manual I found: "You can send a one-page fax in as little as 27 minutes!"

10. Ignorant Managers - Many managers have no clue about the complexity and challenges that the documentation department faces. The usual response when presented with requests to improve the documentation quality and processes is "Documentation? Hey, I use Word - don't you guys?" The higher the manager, the greater the ignorance. It's probably because of the neckties they wear - it cuts off the oxygen to their brain.

Conclusion
Every generation and every profession faces its own plagues, and it's true that some plagues are "gentler" than others - managers like to call these plagues "challenges." Challenges are tough but they make us grow. Both Passover and Easter celebrate growth and redemption. Therefore, may we and all our documentation be redeemed this year, and may we all avoid as many of these plagues as possible.

Thinking of hiring a tech writer? Check out these articles

noreply@blogger.com (Milan Davidovic) — Thu, 17 Apr 2008 02:50:00 +0000

I have links to three online articles over on my own blog.

If you have a bit of time, have a look at one or more of them and then leave a comment here on the STC Toronto blog telling us what you think -- or write your own blog post, if you've got plenty to say. I'd be particularly interested in opinions from anyone who has hiring experience.

The Rennie Charles Award

noreply@blogger.com (Word-Nerd) — Wed, 16 Apr 2008 14:36:00 +0000

I did not know Rennie Charles, but from numerous accounts, he was a special person who gave a lot of himself to the STC Toronto chapter. A number of years ago, our chapter created an award in his memory and the cut-off date for recommendations for the award is 30th of April.

Please consider nominating someone from within our chapter - I can think of several candidates myself.

What qualities are needed in order to be recommended? Since I cannot improve upon the sentiments from the February 1998 article in Communication Times, I am having it republished here in a slightly edited form. It explains it all.

--by Sara Durning, Carla Salvador, and Kim Van Rooy

"Once again, we invite all members to make recommendations for the Rennie Charles Award.

It takes many dedicated and creative volunteers to make a chapter as strong and vigorous as the Toronto chapter, and every June we formally recognize those who have contributed to our growth and success during the previous 12 months.

For more than a decade, we have presented the Rennie Charles Award to one or, occasionally, two members who have made an “outstanding contribution” to the Toronto chapter in the current year or over the past several years. Every member is eligible for consideration, except those who have already won, and all members are welcome to make recommendations.

Rennie Charles is remembered by long-time STC members as a “dedicated leader and a good friend” and as a “sweet, delightful gentleman” who was cherished for the “ideas, support, patience, advice, and mirth” he shared with the Toronto technical writing community. He was twice the President of our chapter, an STC Associate Fellow, our director-sponsor, an STC board member, and a proud Canadian. Rennie was also one of the leaders who reenergized the Toronto chapter in 1985.

Rennie was known for constantly giving of himself to make things happen in the STC. If this reminds you of someone who has made an outstanding contribution to your STC experience, perhaps you could recommend them. Mention one or two specific reasons why you chose this person and submit your recommendation by April 30.

We will review all your suggestions and present a short list to the Toronto executive. The person or persons selected will be announced at the June meeting."

STC Volunteers Needed!

noreply@blogger.com (Andrew Brooke) — Tue, 15 Apr 2008 17:24:00 +0000

The STC Toronto Community would like to invite applications from all our members for positions as Activity Managers/Assistant Managers and Executive Team members and Assistants for the coming year. Members will need to be nominated or acclaimed for a position on the team.

If you want to take part in blazing a new course for our community, and in making a dynamic difference as a team member, please email the appropriate person in our STC Executive list or contact Sheldon D'Cunha at volunteering@stctoronto.org as soon as possible.

Review: Writing for the Internet

noreply@blogger.com (redactec) — Mon, 14 Apr 2008 18:12:00 +0000

Author: Jane Dorner, Publsiher: Oxford University Press, ISBN: 0-19-866285-8

The book is divided into two parts: A and B. Part B is a quick summary of all the key ideas covered in part A. I liked that each chapter has its own contents list, which makes it a lot easier to jump to specific topics. Each page has a column allotted for an extra explanation of a topic or word, a summary of main points in the page, pointers, or quotes.

Introduction: The chapter explains briefly what Internet is about and how this book can help a reader understand what goes into it. I liked the section Reading routes where it explains to readers in a matrix format, how they can proceed in choosing topics based on what their role is or what they are looking for to achieve their goal. An explanation on various traditional roles in a non-Internet world and how they may merge when it comes to writing for the Internet is also useful to understand all that is involved for such a task.

Communicating online: The chapter introduces writing for Internet as a 'new art'. It explains the use of tone-of-voice and the practicality of emoticons for emails and gives few pointers on netiquette. I felt that the topics The Internet and the Web and Dominance of the Web should have been in the Introduction chapter rather than appearing so late into the book; these topics after emails and netiquette from my view didn't seem to fit here. Other topics include style, voice and readability. How technologies affect writing style on the right column of the Your Style topic gives a funny progressive view of how writing changed from the day of stone tablets to present day.

Internet publishing: The chapter talks about copyright, royalties and fees. A good foresight, having recently seen the strike by Writers' Guild of America. Some notable points were found in the point-wise explanation of differences between paper pages and web pages. I think that the acronyms created for BOOK and WEB are intuitive.

BOOK = Bound Optimally Ordered Knowledge

WEB = World Enabled Business

Considering purpose: The chapter explains about the various factors that need to be considered before creating a web page or a site. It emphasizes on the goals and benefits. I liked the four Ws concept (I prefer to remember it this way) or as the author states it, the Who-What-When-Where quartet. Other topics are Content, Audience, and Profile.

Planning: The chapter discusses the steps involved in any writing process i.e. the idea, the planning stage, the draft, and the editing. The planning here involves more with arranging web pages. The design and layout is explained further with topics such as page widths, page lengths, scrolling, etc. Also shedding light on collaborative writing and hints on the usefulness of having a file or a version control system when working in a team.

Good web writing: The chapter deals with some aspects of actual writing with elements related to a web page such as the use of white spaces, chunks, headings, and lists. Mostly has a list of do's and don'ts of word processing. I did learn something interesting in the section where the author talks about some types of writing such as the tadpole and the party game. At the end, it summarizes all that would work well for writing a web page. It is one of the three core chapters along with 4 and 6.

Web nuts and bolts: editing: The chapter emphasizes the importance of editing by a fresh set of eyes. It has pitfall topics such as dangling phrases, ambiguity, redundancy, unnecessary words, etc. A note on how punctuation actually appears on the web is provided.

The last two chapters Web genres and Keeping readers discuss various types of websites and what one can do to keep a reader engaged to a website. Shows some examples of a personal home page and a small company page.

In conclusion, I think that this is a reference book and has an easy to read format. If you are a writer solely doing the content and are in many ways not involved in the design and layout aspect of a web page, then you can skip a lot reading and jump into chapters 5 and 6 and Part B. But, on the other hand if you are someone who's planning to do some web design, layout, and writing then there's lot of helpful information available. Core chapters for this book are 4, 5, and 6. They deal with planning, writing, and editing.

All through the book, explanations are backed by charts and diagrams for additional support as needed; and it has few funny cartoons to keep it a light read. As suggested, the book does not deal with technical content except for some basic HTML code snippets and assumes that the reader is familiar with Internet in the sense that he or she has been online more than once and can navigate web pages.

For more about Jane, visit www.editor.net.

Computer Classes for Seniors

noreply@blogger.com (Andrew Brooke) — Fri, 04 Apr 2008 19:37:00 +0000

From May 5-6, Christy Jackson will be delivering a course at Front Runner training for adults aged 55+ who are beginners at computers and want to learn more.

Location: Front Runner Training, Yonge & St. Clair

Cost: $10 per class, plus textbook for all four classes $15 (optional but recommended)

Course Description

Introduction to Computers - Monday, May 5th, 10am - Noon

For absolute beginners! Learn computer basics in a friendly, non-threatening environment.

The Internet & the Web - Monday, May 5th, 1pm - 3pm

Instruction and advice on surfing the World Wide Web.
Prerequisite: Introduction to Computers or equivalent skills.

Email for Beginners - Tuesday, May 6th, 10am - Noon

Everything you need to get started emailing your family & friends.
Prerequisite: Introduction to Computers or equivalent skills

Digital Photography - Tuesday, May 6th, 1pm - 3pm

Learn how to work with digital photographs on your computer.
Prerequisite: Introduction to Computers or equivalent skills

To register, please call Front Runner Training at:
416 515-0155.

Single-Sourcing Madcap Flare with FrameMaker

noreply@blogger.com (Andrew Brooke) — Mon, 17 Mar 2008 19:39:00 +0000

Flare is a relatively new online help development tool. In addition to being a content creation tool, you can use Flare to import Microsoft Word or Adobe FrameMaker documents and generate a wide variety of online help formats. This review focuses on using Flare with imported FrameMaker files.

First, a bit of background. MadCap Software is the developer of Flare. It originated from another famous online help tool development company, eHelp, formerly Blue Sky Software, which made RoboHelp. After Macromedia bought eHelp, support for RoboHelp eventually stopped. Later, in the world where the big fish continually consume the smaller, Adobe, perhaps the biggest fish of all, bought Macromedia, acquiring RoboHelp, which is still available today.

Mike Hamilton was the Product Manager for RoboHelp since these early days. After the takeover, he, along with many of the other eHelp developers, left the company to join a new one, MadCap Software. Mike is now the Vice President of Product Management there. I had the pleasure of seeing him present his “RoboHelp killer”- MadCap Flare - at our chapter meeting in March of 2007. It was a compelling presentation of a brand new online authoring system, designed from scratch, with many impressive features. He also provided invaluable help when I was first learning this product.

Early in 2008, my company had acquired several licenses for Flare 3.1. We were looking to replace WebWorks Publisher 7 (WWP), the tool we used to generate online help from our FrameMaker files. It's a solid program, but not the most user friendly, to put it mildly. To make certain changes, you have to know how to edit scripts, macros, text-based configuration files and XML. In other words, you have to be a rocket scientist disguised as a tech writer.

Initially, I was very impressed with Flare. Although it's a complex program, with a bit of a learning curve, the program's interface is generally sleek and well-designed. Unlike WWP, you don't have to edit configuration files. Unfortunately, I encountered many problems which I will describe here. I admit some of these are minor quibbles, but many are serious enough to preclude me using this product at this time.

I'll start with what I encountered when imported the FrameMaker files into Flare:

The process of importing FrameMaker files into Flare is fairly straight-forward. Most of the work is done in the Frame Import Editor screen. To ensure that your Flare project stays linked to your FrameMaker files, you have to select the following option in the Frame Import Editor > Source Files tab:

What's confusing is that there is another check box, on a completely different tab, that also has to be selected. It's on the Frame Import Editor > Options tab:

Finally, there is a third check box, on a completely different screen (the Basic tab of your target's properties) that also has to be selected!
In the Frame Import Editor > Source Files tab, the FrameMaker files and books that you imported are listed. Unfortunately, you can't resize the FrameMaker Files column, so if you have a long path, you won't see the name of the file:
In the Frame Import Editor > Stylesheet tab, you click the Conversion Styles button to open the Import Styles Editor dialog box. Here you can specify how to convert each property of the FrameMaker styles. The Preview section, which should display how the style looks, does not work. No matter which style you select, the same "no preview available" message appears:
Similarly, in the Frame Import Editor > Paragraph Styles tab, the Preview box does not display a preview:
The main area you work in is the Project Manager. It includes conditional text settings, your imported files, your Flare "skins" and your targets, which represent your generated help file or target. I found it confusing that both skins and target settings control the appearance of the final output, and found myself moving back and forth between these two areas many times to find the setting I needed.
Another area you may work in is the Content Explorer. This contains links to each generated HTML file, and to your stylesheet. For some reason, two stylesheets are listed here (template.css and template1.css) although only one can be active.
Flare's stylesheet editor is quite powerful. There are two views: Simplified and Advanced. The Advanced view allows you to further fine-tune your various styles. In the Simplified view, you can view and even change more than one style at once:

There are some problems when editing individual styles. For example, when applying bold, superscript, subscript or small caps to the font of a style, the Preview box doesn't show the changes:
After setting up the template, I generated the project to produce WebHelp help project files. The generation time was quite long, certainly longer than WWP.

The remaining problems described next occurred in the generated content.

In the table of contents, some of the headings were missing words:

Specifically:
- Roles in should be Roles in IStream Writer.
- Understanding Elements should be Understanding IStream Writer Elements.
- Documentation should be IStream Writer Documentation.
The problem is caused by the fact that IStream Writer is actually a FrameMaker variable. I've confirmed with MadCap that Flare has trouble processing variables. As a result, variables in headings will not appear in the TOC headings. Also, in some cases, in the text itself, spaces that follow the variables are missing, causing the words to run together. Here, for example, the word Writer is a variable, and the space after it has been removed by Flare:
There were problems rendering graphics properly. In our documents, we use large, high quality graphics so that they will display well in our PDFs. The size is scaled down within an anchored frame. Obviously, we don't want the original size showing in the help files. There's an option in the Frame Import Editor > Options tab that is supposed to retain the image size you've set in FrameMaker:

Unfortunately, this check box has no effect in the current version; the image will appear in its original, oversized dimensions. This problem has been somewhat addressed in the next release, version 4, which I was able to receive as a beta. In this beta, the image is now at the correct size, but the quality is very poor. MadCap tech support stated that this is because of the way Internet Explorer scales down the image, therefore claiming that it's the browser's fault and not Flare's. However, WWP renders the images correctly, at a good quality and at the correct size.

To resolve the graphics problem, MadCap suggested that we resize all our graphics to improve the quality, which is not an acceptable solution. First, there are thousands of these files, so it would take a long time. Second, we want the image size to remain high for our PDF outputs. Finally, even if we could fix the graphics, the text callouts around the graphics also render poorly.

I wanted to include a screenshot that would indicate the poor image quality, unfortunately, now the graphic is completely grayed out, even after doing a full regeneration. You can still see, though, that the text callouts are rendered poorly:

I admit that other graphics have fared better, but I can't explain why this particular one has vanished.
The Browse buttons don't navigate you in the order of the topics, but instead in the sequence in which you've browsed the topics.

Because users can already use their browser's forward and back buttons to view the topics in the order that they had browsed the topics, there is no reason to duplicate this functionality. In WWP, the browse buttons correctly move users through the sequence of topics as they appear. MadCap has told me this has now been logged as a defect.
I had problems getting the numbers to line up – see how the number 10 is improperly aligned?

The number 10 should be slightly over to the left so that the decimals line up. Also note again that there is no space between the word The and IStream Writer, because IStream Writer is a FrameMaker variable.
Another major problem with Flare is that there is no effective table management. FrameMaker's table styles do not appear in the table styles portion of the stylesheet editor. Instead, many different numbered td.Cellclass styles appear:

It makes no sense to have dozens of td.CellClass styles being generated, and there is no way to know which one applies to which table throughout the document. There should be a one-to-one mapping of FrameMaker tables to Flare styles, as WWP does.

MadCap Flare has tremendous potential, but suffers from problems that are all too common in the software industry: it tries to do too many things, and in the process, falls short for specific tasks. I'm hopeful that all of these problems will be addressed in a future release.

In the meantime, if you're looking for a solid, mature, dependable tool to generate online help from FrameMaker, stick with WebWorks Publisher, which is now called e-Publisher.

Update: I submitted this review to Mike Hamilton, but have not heard back from him.

March meeting last week

noreply@blogger.com (Milan Davidovic) — Mon, 17 Mar 2008 00:51:00 +0000

OK -- I'm back, and I missed last week's meeting. I'm looking for people to leave a comment for this blog post and tell me (and the rest of us who couldn't make it):

What did you like about the speaker and the way she gave the presentation?

What specific information did she provide in her presentation that you are most likely to act on in the near future?

Alternatively, drop me a line at milan.stc.toronto@gmail.com and let me know.

Thanks...

March meeting next week

noreply@blogger.com (Milan Davidovic) — Thu, 06 Mar 2008 03:22:00 +0000

So, it turns out that I'm not going to make it to the March chapter meeting (Vivian Aschwanden, "The Importance of Being Earnest...") either. So, as I did before, I'm going to ask people to tell me about it and turn their answers into a blog post.

My questions as before:

What did you like about the speaker and the way she gave the presentation?

What specific information did she provide in her presentation that you are most likely to act on in the near future?

In the meantime, if you attended the February meeting (Nicky Bleiel, "Cool Tools for Tech Writers") and I didn't ask you about it already, go to my blog post about it and leave a comment.

Winter/Spring Season of EAC Seminars

noreply@blogger.com (KenWeinberg) — Tue, 04 Mar 2008 16:14:00 +0000

The Toronto branch of the Editors' Association of Canada offers a wide range of practical, affordable seminars for editors and writers. Half-day, one-day, and two-day seminars on topics such as

Eight-Step Editing

Proofreading

Subcontracting

Editing in Adobe Acrobat

Writing and Editing Advertising, Sales, and Marketing Materials

and many others are available from $85.

Full-day and two-day seminars include lunch.

For more information, visit http://www.editors.ca/branches/toronto/seminars/index.html, or call 416 975-5528 or email toronto@editors.ca.

Professional Writers Association of Canada 2008 Seminars

noreply@blogger.com (Word-Nerd) — Fri, 29 Feb 2008 15:15:00 +0000

Professional Writers Association of Canada (PWAC) is delighted to announce the 2008 PWAC Presents seminar schedule.

The series provides a choice of five half-day seminars on specialty areas of writing to help you and your business communicate more effectively.

You can register for one or come to them all, as best suits your needs!

Topics in the 2008 series include:

White Paper Writing 101 - Friday, 14th March
Writing for Success on the Internet - Wednesday, 30th April
How to Earn $ Writing Promotional Materials - Tuesday, 24th June
Media Release Writing - Tuesday, 30th September
Speech Writing - Tuesday, 25th November

Location
Centre for Social Innovation, Suite #120, 215 Spadina Ave. Toronto

Time
Each session runs from 9:30am to 12:30pm on the date specified.

Cost
Single sessions are $42 for PWAC members and $63 for non-members. Group and multi-session packages are also available.

Presenters
Presenters are PWAC members and experts in their seminar topic.

For more information about sessions, presenters go to:
http://www.pwac.ca/eventsandresources/pwacpresents

To register please go to:
http://www.pwac.ca/eventsandresources/pwacpresentsregform

If you have any queries please do not hesitate to contact PWAC National Office at info@pwac.ca

February's chapter meeting -- a few thoughts

noreply@blogger.com (Milan Davidovic) — Wed, 27 Feb 2008 02:08:00 +0000

I couldn't make it to the last STC Toronto meeting ("Cool Tools for Tech Writers", Nicky Bleiel), so I asked some people to tell me what they thought of the speaker and what they made use of from her presentation. If you also attended, please use the Comments function to add your opinion of the presentation.

(Thanks to Elizabeth Pollack, Michèle Marques, and Todd Race for the answers that follow.)

What did you like about the speaker?

She was lively, knowledgeable about the topic and provided instances where she used the tools in her day-to-day working life. She also didn't get flustered when the tools did quirky things in the middle of the demonstration.

=====

I liked that she had a handout listing all the tools she mentioned, so that we didn't have to take notes for those details. I also liked that she was open to other people mentioning their favourite tools for particular areas, which made the meeting more participatory.

=====

She's a tech writer with experience and able to relate these items to our world. She didn't take herself too seriously and was able to keep things moving along with an appreciation for the flow of the evening.

What specific information did she provide in her presentation that you are most likely to act on in the near future?

Right after the meeting, I:

Downloaded the Gimp. It it much more useful than the other "free" image manipulation software I had downloaded. I plan on playing with / using it often.

Removed document metadata using Office 2007.

Reviewed Wiki tools at http://wikimatrix.org.

I also plan on reading "Free or Open Source Tools for Technical Communicators" and "Useful Shareware and Freeware for Technical Writers" when I have a spare moment or two.

=====

I'll have to check out "the gimp" ... it's been a long time since I last looked at that image editing tool, and it seems a lot friendlier now. I already use some of the other cool tools she mentioned - SyncToy, Snagit, Sharepoint. And, not part of the presentation in the same sense - the speaker works for Component One and had a door prize draw for DemoWorks. I was the lucky winner :-) and will be trying it out.

=====

I was especially intrigued by the overall discussion about blogs and podcasts (ie Web 2.0) and also about Sharepoint (and how Nicky brought Sharepoint into a discussion of tools < $100)

The Incomplete Guide to Gödel

noreply@blogger.com (Andrew Brooke) — Fri, 08 Feb 2008 17:54:00 +0000

Kurt Gödel was an Austrian-American mathematician who lived from 1906 to 1978. He’s best known for his incompleteness theorems, which have had a tremendous impact not only on mathematics but on other sciences and even philosophy.

Gödel’s theorems were actually a response to the ideas of another mathematician, David Hilbert. Hilbert had a dream of creating a complete, accurate and consistent system for all the mathematical principles (or axioms) that had been discovered to date. Earlier, some of these axioms were discovered to be wrong, so there was tremendous pressure to ensure such errors would never occur again. Hilbert wanted to establish a solid foundation for all mathematics, now and forever.

Sounds like a great idea right? There was just one problem – to create such a “perfect” system is impossible, and Gödel proved it. He demonstrated that if you created a complete system that described every mathematical truth, it would contain some statements that could not be proven. In other words, the system would be complete but not fully predictable or accurate. Conversely, you could create a system that is fully provable, but then it would not be complete.

How Gödel did this is incredibly complex, but I will try to explain. He essentially created a mathematical system using a complex numerical notation, where one of the statements in the system was: This statement cannot be proven.

Now, if this statement could not be proven, then the system might be complete, but it would contain a non-provable statement, making the system itself inconsistent. But, if the statement is provable, then it means the system still contains a non-provable statement (because the statement itself says it can’t be proven) and therefore the system itself is still not fully provable.
As a workaround, we could just leave this pesky statement out of the system, because it's causing so many problems. However, if we do that, then the system would be missing a statement, making the system fully provable (yay!), but incomplete (boo!).

To summarize, Gödel was saying that any system can be:

complete but not fully provable
or

fully provable but incomplete

This was Gödel’s first incompleteness theorem. His second theorem went further and said that any system can never be complete. That is, any system containing true statements will always be missing some statements, but you can never know what they are. (If you did, then they wouldn’t be missing, would they?)

The philosophical impact of Gödel’s theories are enormous. Extrapolating his ideas, it means that we can never know everything, and that even if we could, some of what we know could never be proven.

The implications for information developers should be clear. All documents are essentially collections of statements, namely theory and procedures. It is impossible to create a document that is complete, and we don’t even need Gödel to show this. Users are complex beings and therefore completely unpredictable. Compounding this is the fact that the product being documented (especially if it’s software) is also unpredictable. Mathematically, we would express these two facts as:

user unpredictably x product unpredictably = lots and lots of unpredictably

It is therefore impossible to create a complete guide that would explain every possible situation. Even if you could, it would contain statements that are not true. Again, we don’t need Gödel to prove this. Too often we see guides that try to be complete, and in doing so sacrifice quality and accuracy. That’s why the mantra of every tech writer when responding to pressure to quickly complete the draft should be: “Do you want it fast or do you want it right?”

More importantly, if you really did try to create a complete guide, it would have a size approaching infinity, which is a rather large number. Some of the best examples of documentation are quick start guides, usually just a few pages, or as a fold-out poster. Size does matter, but not in the usual way, because less is often much, much more.

This column is now complete, but of course I cannot prove a word of it.

Writing and Grammar Course: Front Runner and Toronto STC Promotion

noreply@blogger.com (STC Toronto President) — Mon, 04 Feb 2008 13:49:00 +0000

As an ongoing part of any partnership there is a need to offer support to one another. Front Runner Training has been an active partner with the Toronto STC in a variety of ways and they are continuing with that partnership by offering us promotional pricing on an upcoming course. The course titled Writing & Grammar will be held on two upcoming Saturdays: Feb. 16 & 23, 2008.

The Four Portable Rules of Grammar - John Samuels

John writes, in part:

"When I was asked to teach writing and grammar, two thoughts immediately crossed my mind. How do you teach something that is so essential, so complex, but so "to the average person" boring, without putting an entire class to sleep? The answer lay in two main ideas: I have learned more by correcting someone else's bad grammar, and people use better grammar when they talk than when they write.

I avoid teaching the language of grammar and focus on the uses of grammar.

The bulk of the course has the students write non-stop for five or ten minutes, then edit each other's work. When a particular problem is discovered, the review stops and the questions begin. Why does this not work? How can we make it work? That is, a need is created, and then the theory is taught.

The result is a set of four basic rules that students can easily recall and use whenever they write."

To learn more about John's four rules of grammar, take the two day workshop, conveniently scheduled over two Saturdays, so it won't affect your weekly work schedule!

Click here for detailed outline, pricing and date information
http://www.front-runner.com/training/outlines/writing/writing_grammar.html

Register and pay now for February's course - Toronto STC members receive a 10% discount on this specific course.