Archive for Technical Writing

The Future of the Book

With touchscreen technology poised to become a ubiquitous part of our lives, the future of the book is likely to change dramatically as well.

From TED.com – “Software developer Mike Matas demos the first full-length interactive book for the iPad — with clever, swipeable video and graphics and some very cool data visualizations to play with. The book is Our Choice, Al Gore’s sequel to ‘An Inconvenient Truth’.”

Learning Adobe Illustrator

In 2010, I determined that I wanted to improve my Adobe Illustrator skills and so I started creating a mandala a month. Below is the final result.

Copy Editing English for a Globaliz(s)ed Audience

In one of the courses I teach at BCIT (British Columbia Institute of Technology), I received an email from a very keen participant asking how to prepare for the course (Technical Editing and Grammar course – 1008). Inspired by such enthusiasm (this is what makes September great!), I decided to take it further and include  information for anyone interested in improving their core skills as a technical writer.

Get a Quality Style Guide – Consider ordering the Chicago Manual of Style (I have both an online and hard copy version). It’s an excellent investment for anyone interested in high-quality English-language writing.

Learn MS Word – Research the Track Changes feature in MS Word. There are other software programs technical writers need for writing, but MS Word is still the most common. As a technical writer, you’re expected to use Word at an advanced level.

Learn hard copy markup – It may seem archaic, but hard copy markup makes you indispensable when editing and developing large documents).

Learn the Most Common Grammar Errors – In my course, we learn the ten-top grammar errors. Don’t feel you have to know all grammar errors (that’s what a good style guide is for), but your credibility as a writer is increased exponentially if you know the core ones. To find out the ten-top grammar errors, take my course.

Write, write, write! – to get your foot in the door, take every opportunity you can to write and edit even if it means working for free. Ensure you ask low paying (or non paying) clients to let you keep a copy of the before and finished versions, so you can use them to market yourself.

Saint John Transit gets Wireless Upgrade

SaintJohn-110617-01web

Back in February 2010, Webtech Wireless expanded its InterFleet® implementation with the city of Saint John, New Brunswick to include an additional 100 public works and police vehicles—a contract valued at over $100,000. Now to complement the city’s Interfleet solution, Saint John Transit also plans to deploy a Webtech Wireless solution—NextBus.

NextBus will provide Saint John Transit with an AVL tracking solution for its 60 buses, allowing riders to check bus arrivals in real-time. Using PCs, landline phones, cell phones, or SMS text messaging, riders get real-time travel information (each bus is fitted with a satellite tracking system) designed to help them decide whether catching the next bus is a sprint or leisurely stroll. Currently, riders can only view a static schedule of intended bus arrivals and departures on the company’s web site.

NextBus will also install five LCD screens at various locations around the city, including McAllister Place Malland the university campus (UNBSJ) and LED screens at bus stops. To help make public transport more attractive to potential riders (and as a nod to Saint John Transit’s already existing environmental initiatives), the service will add to the city’s existing hot spots with free WIFI for riders on all its buses.

About NextBus

A subsidiary of Webtech Wireless, San Francisco-based NextBus implements real-time passenger information systems used by dozens of transit agencies, universities and other transit operators across North America. Because traffic variations, breakdowns, and day-to-day problems faced by any transit provider can interrupt service, NextBus was designed to help keep riders on schedule even if their buses aren’t. NextBus uses satellite technology and advanced computer modeling to track vehicles on their routes.

As Canada’s oldest incorporated city and New Brunswick’s largest municipality, the city of Saint John has been providing municipal services for more than two centuries. According to Statistics Canada, the Saint John municipal area has a population of 122,389, with a population density of 36.4 persons per square kilometre.

old_saint-john

Historic Saint John has been a transportation hub since long before confederation.

The Port of Saint John is one of Canada’s most important ports (its relatively mild maritime climate keeps its deep-water harbour ice-free year round when inland ports in the St. Lawrence Seaway must contend with ice). This keeps the city’s businesses and industries bustling throughout the year. In 2010 for the first time ever, the Port of Saint John exceeded 30 million metric tonnes of cargo in a single year.

About Saint John Transit

Saint John Transit was established in 1979 to provide scheduled transit service to the city. It replaced City Transit Limited (1948-1979) and a string of others dating back to the People’s Street Railway Company (1869-1876). Saint John Transit is the largest public transit system in the province, both by mileage and passengers.

Saint John Transit Statistics

Saint John Transit’s ridership is approximately 50 percent higher than the average for Canadian cities with a population of between 50,000 and 150,000.

  • Number of vehicles: 60
  • Ridership: 2.5 million riders per year

Current active fleet bus types:

Greening Saint John

To reduce auto emissions, the City of Saint John, along with the Federal and Provincial governments, is investing in public transportation between uptown Saint John and outlying communities. Branded as ComeX (Community Express), it provides a rapid bus transport service during peak commuting times.

Source: Statistics Canada, 2006 Census of Population.

Source: Statistics Canada, 2006 Census of Population.

With the implementation of ComeX, greenhouse gas emissions are projected to drop by 1,500 metric tonnes and downtown traffic will decrease by 800 vehicles a day over the next five years.

Using NextBus on Your Smartphone

Below is another excerpt from the Webtech Wireless blog I’ve been working on. As a corporate blog, I try to balance clear concise professional writing with a personable informal tone often not possible in other corporate materials. So, the purpose of a blog is not merely to blast potential readers with the same material they’d find elsewhere, but rather, it’s an opportunity for a company to show  a more human face and reach out a real people.

Excerpt

Just as the adoption of the cell phone became universal a decade and a half ago, the smartphone is now a ubiquitous part of life for most urbanites. According to New York Times writer, Damon Darlin, “historians will remember the advent of the smartphone as something as important as the elevator, air conditioner and automobile.”

The implication for transit companies is clear: adopt an AVL solution or face irritation and disinterest from your ridership. Fortunately, transit authorities are reading the writing on the wall and many of them are choosing NextBus—for its reliability and simplicity.

“NextBus, a wonderful Web site that monitors the arrival of city buses in many big cities, is a godsend.”

While there is no official phone application for Nextbus, the simplicity of the NextBus website makes it easy to use on most smartphones.

To access NextBus using a smartphone:

  1. Using your smartphone’s web browser (such as Safari), access the NextBus website: www.nextbus.com.
  2. Choose the mobile version or the full-featured website.
  3. Select your location, your transit agency, your route, and then your stop.The most current prediction for the arrival time of the next vehicle is displayed.
  4. You also can add your stop info to your home screen so it will be instantly available.
  5. If a prediction is already displayed on your smartphone, simply push the ‘refresh’ link at the bottom of the page to get the most up to date information.

Usability Fun and Games

I convinced myself that applying for a job through the IBM web site was a good use of my time, but I didn’t factor in how much fun it would be.

Like many mega corps, the IBM site asks us to upload our résumés and then goes on to ask us to enter all the same information again manually, field by field. By the end, we’re likely to conclude that any job we should ever get at IBM will net us similar mindless work. But who knows, filling out online applications is my form of Vegas—’cause ya’ never know…

Here’s the kicker. In the section for language competency, I was given a list of languages and a ranking system from which to choose: fluent, intermediate, basic knowledge, and no knowledge. I don’t know what the value is in adding information about a skill in which one has no knowledge. I mean, I could go on and on.

I couldn’t help myself, so I obliged!

No Knowledge required

Three Ways to Improve Your (Technical) Writing Skills

I get asked more frequently about how to make inroads into the field of technical writing and my response generally comes down to three key points:

  1. Get educated: Many technical schools and universities have technical writing programs. They often offer their courses on an iterative basis (i.e., you don’t have to commit to the entire program; you can just take a course or two to try it out). Apart from the training you’ll get, formal training is also a great way to network and immerse yourself in the milieu of technical writing.
  2. Get Informed: Check out the job boards and read the requirements for various jobs in technical writing. If you find the requirements daunting—don’t be discouraged. Many job descriptions are little more than wish lists, but they’ll give you an idea about the kind of skills you’ll need to succeed and the range of industries that need technical writers.
    Tip – rather than searching for “technical writer” over a large date range, I view all posted jobs in, say, the last three days. Positions that require technical writing skills are frequently posted under other names than “technical writer”.
  3. Get involved: Find opportunities to write—don’t wait for a paying job. You may want to volunteer with some non profit or other group as a writer just to get experience. Everyone needs good writing and if you can provide it, you’ll start to acquire samples of work (ensure that any freebie work you do comes with the understanding that you’ll use finished writing as samples of your work).
    I volunteer as a writer for the Vancouver Observer (an online magazine) and it is definitely helpful for keeping my writing skills honed as well as for networking.

Some notable Vancouver job boards:

Seminar: What’s the real job of a technical editor?

The Editors’ Association of Canada-BC presents

What’s the real job of a technical editor?

A One-day Seminar

Editors' Association of Canada

If the job of the technical editor is to make complex subjects accessible to normal people, why is it that so many technical documents fail. What is the real job of a technical editor?

Using real-life examples and humour, Jason will demonstrate just how spectacularly technical documents can fail and how you can become an advocate for excellent documentation. This hands-on workshop helps you assess your own skills while exploring what it is technical writers do. By the end of the workshop, you’ll have developed your own toolbox of skills that technical writers need to succeed.

When: Saturday, November 27, 10 AM- 4 PM

Where: SFU Harbour Centre, room TBD
515 W. Hastings St., Vancouver, BC

Instructor: Jason Hall

Cost:

  • Early Bird (on or before Friday, Nov. 12, 2010) Member: $100.00  Non-member: $160.00
  • After Nov 12: Member: $100.00  Non-member: $160.00
  • Note: Registration closes Friday, November 19 at 5 Pm

Register

About Jason Hall

Jason Hall has over 15 years of technical writing and training experience and brings excellence to all his documentation endeavours. He has prepared industry-relevant user manuals and training materials for a great variety of industries from law enforcement to inventory management to health care software products. Past clients include SAP, Best Buy, WorkSafeBC and Health Canada. Jason is comfortable with the full documentation development cycle including interviewing subject matter experts, creating documentation needs analyses, and converting product specs into accessible end-use documentation.

Writing for the Web: Clarity 7/7

Use Standard English

Replace the non-standard English words with their English equivalents. Word constructs like ‘and/or’ and ‘he/she’ are technically not words, so you should avoid them as much as possible. This is a good approach, because it’s easy to rely too much on them even when there is really not logical need. Take for example, “You can call and/or write to request a free estimate”. There’s no real need to say ‘and/or’ in such a situation.

How would you rewrite the following to remove and replace non English words?

  • Our global portfolio (accessed via our web site) invests in U.S. and/or foreign markets (i.e., commodities).

Writing for the Web: Clarity 5/7

Avoid Ambiguous Pronouns

The best way to avoid this kind of confusion (what kind of confusion? The confusion that results from ambiguous pronouns), is to read your copy carefully checking that you can easily identify the noun that belongs to the pronoun. If more than one noun emerges as a possibility, replace the pronoun with its intended noun.

What’s rolling toward second base?

  • The ball
  • The wall
  • Winfield’s head