STC Toronto Chapter Newsletter

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 lable each container?

The obvious lables 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 lables 'Our dog' and 'David's dog', eliminating all confusion.

Lables 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 lables, 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.

Lables 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 lables, software lables 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 labled, 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 imbed 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 lable 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 lable 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 lables carefully - they can turn good documentation into great.

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

Labels: dogs, lables

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.

Labels: human factors, information architecture, page design, usability, Web, Web site design

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.

Labels: gas

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

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.

Labels: software, tools

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?

Labels: Brenda Martin

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.)

Labels: general meetings, Web