Focus on Technical Writing

Use Active Voice

Use Active Voice

Tricky Dick

The phrase, “Mistakes were made” is attributed to US President, Richard Nixon, to acknowledge that the Watergate situation was mishandled. He could have spoken in active voice and said, “Mistakes were made by me” or better still, “I made mistakes”, but he evaded direct admission of responsibility and thereby went down to history as Tricky Dick.

There are three times when it’s appropriate to write in the passive voice:

  • When the doer is unknown. “My bass clarinet was removed.”
  • When the doer is unimportant. “The lab rats were given a placebo.”
  • To protect the doer from embarrassment. “You were overcharged for your purchase.”

TIP: In technical writing, you can distinguish between general concepts and action-oriented procedures by writing the former in passive voice and the latter in active.

Using active voice in web writing adds interest and action to your writing. Good sentences begin with a clearly stated subject (the doer) and a strong verb (action). While it is a commonly used verb, “to be” is passive as it describes a state of being rather than doing. So the more you use “to be”, the more passive sounding your writing will be. Also, some verbs are weaker than others. The verb “to understand” is weaker, because it is harder to quantify and tends to get lumped with another verb that’s doing the real work.

EXAMPLE: To understand how to run for President of the United States, you must have friends in high places.

 

Use Concrete Specific Words

Use Concrete Specific Words

StuffnJunkUsing concrete specific words won’t necessarily make your writing shorter, but it will make it more interesting to read.

Avoid:

  • Several – how many?
  • Numerous – What number?
  • Various – Which?
  • Very – use your imagination!

And of course:

  • Stuff
  • Junk
  • Whatever!

 

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

Type: Case study
Objective: Describe how NextBus solution works
Purpose: Data-driven improvements to bus service
Audience: Municipal transit decision-makers

 

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 Mall and 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.

Training course design samples

Type: Training plans 
Objective: Describe how new course will be organised 
Purpose: Enable course designers to build course
Audience: Instructional designers, instructors

 

Course Design Samples

One of the major problems I encounter with technical training and documentation is that it so often focuses on product features rather than real-world tasks users need to do their jobs. My approach is to start with learning objectives and an audience profile and then seeing how the technological feature fits in.

The following samples show a sample course design done for a course at BCIT:

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

Discovering Vancouver’s hidden music makers

Type: Magazine article
Objective: Feature a local musical instrument maker
Purpose: Build appreciation for complete arts picture 
Audience: Subscribers to digital magazine

Up in the hills of West Vancouver, there is a house entirely furnished with harpsichords and other exotic early keyboard instruments. They are the work of Craig Tomlinson, one of Canada’s two makers of early keyboard instruments.

Craig began instrument building at 16 with a simple dulcimer. It now hangs on the living room wall, a reminder of his modest beginnings amidst the collection of harpsichords, clavichords, virginals, and fortepianos.

The revivalist movement in musical-instrument making began in the 1930s and, by the 1960s, classical music circles began to appreciate what original instruments could bring to performances of the great Baroque masters (Bach, Handel, Vivaldi and so forth).

In 1975, Craig was asked to work on a two-manual French harpsichord. The challenge of this task opened up a new world for him. He worked on kit instruments over the next few years, but could hear and see the limitations of factory-produced kits. So in 1978, Craig headed down to Berkeley to learn the craft of building early keyboards. This led him to a rediscovery of the building methods of old-world craftsmen, after whom he modelled his instruments.

“The harpsichord I envisioned combined a perfect balance between the tonal intricacies of the sound and the beauty of the instrument and its decoration,” he said.

My tour across Craig’s living room was chronological and, although time seemed to fly, I know 350 years of keyboard development passed before I reached the other side.

Gazing at the collection, I asked Craig if people who buy his instruments are performers or simply collectors. He said that most buyers are in fact performers, although he cited one large glossy magazine in Palm Springs, California that posited the notion that you’re not really on the ‘A’ list until you have your own French Double Harpsichord.

Virginal

The grand old lady by the front door is an exquisitely ornate 1608 virginal. She was inspired by two 17th century Flemish instruments made by the Ruckers family of Antwerp. I was so entranced with the sheer beauty of this instrument that I could hardly follow his description of its nifty short octave bass, which expands the lower octave downwards by replacing the chromatic black notes with diatonic white tone pitches (although, you wouldn’t know to look at it). Sorry for the tech-speak, but I think this means that the player can play down to a G below the expected low C, but my eyes were feasting on the trompe l’œil, elaborate Latin mottos, and swirling arabesques.

As with all of his instruments, the virginal was painted by Craig’s mother, Olga Kornavitch-Tomlinson. An artist in her own right, she decorates the instruments by combining historical authenticity and her own instincts as an artist.

Harpsichord

The harpsichord in is a replica of one Craig received a Canada Council grant to travel to Scotland to research. To research the instrument (this one was based on a Pascal Taskin of Paris, now residing in a collection in Edinburgh), Craig had to photograph, measure, disassemble, and incredibly, even get inside it.

Perhaps to dispel the notion that early music people don’t have a sense of humour, Craig told me the story about the Scotsman who snuck up on him while he had his head deep inside the 1769 harpsichord, and thundered the “biggest and loudest chord” Craig had ever heard played on any harpsichord.

Once again, there was a techie segment to the tour and Craig showed me the transposition block, a slab of wood used to shoehorn the instrument up and down in pitch.

In an age of globalization and standardization, it’s hard to imagine some of the madness that goes on in musical circles with regard to pitch. North American orchestra’s tune to A=440 Hertz, while their European counterparts tune to A=442 (or A=444 if you’re in Vienna, or A=444.5 on Kärntner Strasse between the hours of 3 and 5 pm). Geography plays a part in pitch, as does time. In fact, pitch has crawled up steadily since the heydays of most of these instruments. Since Bach was around, they’ve crawled up to the tune of a full semi-tone.

Curiously, this rise of an exact semi-tone makes the transposition block possible. Craig pulled the block out from the left side of the keyboard, shunted the keyboard to the left (into the vacant place), and then pushed the block into the right side and, voilà, the entire instrument now played a full (Baroque) semitone lower.

Clavichord

The clavichord dates back to the 1400s, but the instrument in Craig’s studio was a replica of one from 1784. Curiously, its visual simplicity seemed downright West Coast, reminiscent of the beautiful Arts and Crafts style furniture I’ve seen on Salt Spring Island and the Sunshine Coast. Craig attributed this to the cherry wood and, of course, its admittedly unembellished appearance.

He doesn’t play much any more, he said, but showed me how difficult an instrument a clavichord can be owing to its soft, but exacting touch. There’s no margin for error. He tapped a few neat and precise chords and the instrument whisper shyly. Take note you who might be thinking of buying one of those condos in False Creek—this is the instrument for you. It has a projectional range of about three feet, guaranteed to disturb no one, and it’s very soothing on frayed nerves.

Fortepiano

There’s a funny thing about the origin of the name of the modern instrument, the “piano”. In 1713, when harpsichord maker Bartolomeo Cristofori invented an instrument that could play both soft and loud (unlike the harpsichord), he called it a “loudsoft” or fortepiano. This was the instrument Haydn, Mozart and Beethoven wrote for (well, before old Ludwig smashed his to bits that is), and it was the immediate precursor to today’s pianoforte. You say fortepiano, I say pianoforte.

The name difference seems moot, but the two are quite different. While the fortepiano can and does have dynamics, it was no match for the thundering sonorities in the age of Romantic composers (Chopin, Liszt, Rachmaninoff) and so it fell from favour when the robust pianoforte appeared on the scene.

In recent decades, an interest in authentic performances of earlier works necessitated the revival of the comparatively delicate fortepiano. In fact, the Vancouver Opera will be using Craig’s fortepiano in their performance of Mozart’s La Clemenza di Tito in February 2011. It is a beautiful instrument based on one Anton Walter built in Vienna in 1795. The original now resides in the Germanisches Nationalmuseum in Nuremberg.

Techie bit: The fortepiano doesn’t have pedals like modern pianofortes; it has knee levers. I’m sure it works better than it appears, but the fortepianist sustains notes by raising a damper rail—with his knees. “The right lever raises only the treble dampers and the left lever raises the entire damper rail”, said Craig. I tried not to resist the uncomfortable imagines of the poor player squirming away on the fortepiano bench, first knees, then legs and, finally buttocks join in.

Workshop

We headed out to the workshop and passed Craig’s son, Brian. Craig remarked that Brian preferred the family Yamaha and the music of the French Impressionists (Ravel, Debussy), and then snorted, “Kids these days…”

Given that the focus of this article is about local craftsmen, I asked Craig if any of the materials were local. Outside of the holly and the occasional raven feather found in nearby Chatwin Park he has used in the quills (the plucking mechanism in harpsichord jacks), he found that he had to use the same woods that builders used two and three centuries ago. He experimented by building a harpsichord using local Sitka spruce, but found the sound “entirely different”.

For this reason, he makes regular pilgrimages to Mittenwald in southern Bavaria—a haven of fine European woods—to buy the Swiss pear, German spruce and boxwood his instruments need. He jokes about the time he beat the Steinway buyers there, leaving them only leftovers. Other woods, such as American poplar, come from the US East Coast.

The workshop has one harpsichord in the works and Craig showed me various phases of its construction. He showed me blueprints made from measurements taken in Europe, which he laid over the instrument, like a dressmaker. In the corner, piles of pear wood, cherry, popular, German spruce, and boxwood waited to be shaped into the exquisite instruments I’d just seen in his house and would one day grace the concert halls of Vancouver and the world.

To order a keyboard of your own or for more information about Craig Tomlinson, see tomlinsonharpsichords.com

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: