Archive for Web Writing

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:

Writing for the Web: Clarity 4/7

Avoid Helping Verbs (Might, May, Would, Should, and Could)

Helping verbs, also called auxiliary verbs, are tricky for two reasons: they can have multiple meanings and those meanings are sometimes a matter of interpretation.

EXAMPLE: “When you complete your timesheet, you should be paid.”

If you insert may instead of should, implies possibility or permission.

EXAMPLE: “When you complete your timesheet, you will be paid.”

Writing for the Web: Clarity 6/7

Check Sentences for Misplaced or Dangling Modifiers

Of all grammatical errors, misplaced and dangling modifiers cause the most hilartity. Let’s face it, they’re just plain fun (as long as it’s not you who writes them). In the words of Groucho Marx, “One morning I shot an elephant in my pajamas. How he got into my pajamas I’ll never know.”

  • A misplaced modifier is confusing because, although the modifier may be correct, it’s modifying the wrong word in the sentence.”We almost ate all the turkey” is confusing because it’s not possible to “almost eat” something. The correction is, “We ate almost all the turkey”.
  • A dangling modifier is confusing because the doer of the action is unclear. “After waiting for three hours, the train left the station.” Who did the waiting—you or the train? It’s not clear.

Another example: “It wasn’t long before the two got engaged, lived in several Canadian cities, pursued their separate career paths and explored their new surroundings while weighing the pros and cons of each.”

What are they weighing the pros and cons of?

  • Their surroundings
  • Their separate career paths
  • Several Canadian cities
  • Their engagement
  • All of the above

Writing for the Web: Clarity 3/7

Simplify the Tense

Unless you’re a time traveller (and therefore comfortable with temporal paradoxes), the best rule of thumb is to stick to the present tense as much as possible and make occasional forays to other tenses as needed.

English has twelve tenses. Present tense is the only real tense—all the others are factors of our imagination, so don’t make time travellers of your readers by hiking around through your imaginary temporal landscapes.

EXAMPLE: “Madonna removed her wedding ring before she appeared last week sparking rumours that her marriage is on the rocks.”

Writing for the Web: Clarity 2/7

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.

Try writing the following sentences in the active voice.

  • The road was crossed by the children.
  • The paint is then allowed to dry for one hour.

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

Writing for the Web: Clarity 1/7

Clarity

Futurama - Stuff n' Junk (or whatever)Using concrete specific words won’t necessarily make your writing shorter, but it will make it more interesting to read. Consider the following:

“A number of factors must be addressed to ensure this effort meets its objectives within the proposed time frame.”

Avoid:

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

And of course:

  • Stuff
  • Junk
  • Whatever!

Rule: Use Concrete Specific Words

Writing for the Web, It’s a Digital Life

It’s a Digital Life

It's a digital lifeWhen writing for the web, you are writing for an audience that’s mostly fickle and distracted. There’s just too much information out there, so readers flit about looking for writing that’s most easily consummable to them. If they encounter any challenge to their reading (poor organization, rambling prose, padded sentences), they bail.

The maxim, “Ride the horse in the direction it’s headed” is appropriate here. If you organize your information in a way that follows how people read, your writing is more likely to be read. Web readers read differently in the following ways:

  • They don’t read screens as easily as pages.
  • They tend to scan and forage for the content they want.
  • They don’t read in a linear fashion—they follow links and move about.

Generally, to get your writing read, write shorter sentences. This principle is widely known, but little information is ever provided on how to write shorter sentences. Over the  next 14 days, I will describe ways to improve the readability of your writing based on the following web-writing principles: clarity and economy. Starting tomorrow…clarity.

Barry Cogswell, Artist & Sculptor

I also want to thank you for helping to make the process so easy and pleasant. It was great working with you. From the beginning you had a very clear idea of how the site might be designed, but you were also more than willing to listen to my own ideas and suggestions. Throughout I found the complete process, from starting with my initial request to taking delivery of your excellent final design a very positive and enjoyable experience. I assure you I will not hesitate to recommend you to acquaintances and friends who may need the help of a web-site designer.

Thank you again.

Perfect Contract

The Perfect Contract

I was contracted to provide technical help, which I would describe as The Perfect Contract. What was perfect about this contract was how much I was able provide because it mirrored my diverse range of skills and abilities. So much so, in fact, that the description of what I did reads almost like my résumé. This contract was a quick turn around – I was called on Thursday and had the majority of work completed by the following Wednesday.

Needs Assessment – 6 hours

The client was in the midst of an office-wide migration from Macintosh computers to Windows PC computers to be compliant with head office. I spoke with their IT Administrator to determine what operating systems were involved and what she thought the key issues were.

I discovered that some Users would migrate directly to PC computers and other would be on their old Apple Macintosh computers running Windows in a Citrix shell for several weeks. My training and materials needed to reflect that.

I explored their system making notes. I needed to know their systems well enough to anticipate a broad range of questions pertaining to both Apple Macintosh and Windows PC operating systems as well as the Citrix Shell. I concluded that I would be giving a lecture type demonstration to all staff using screen projections and handouts.

Create End-User Guide – 11 hours

At home, I created a complementary End-User Migration Guide aimed at both the full PC Users as well as the Mac Users now operating Windows in the Citrix Shell.

Topics covered included Understanding Windows 2000 Server, Using Word and Excel in Windows, Introduction to Outlook, Good PC keyboard shortcuts for Mac Users and how to navigate between the two environments.

Deliver Presentation – 1.5 hours

On Monday, I delivered a presentation to all available staff in their boardroom. I handed out my Guide and used a projector to demonstrate how their new computer environment would operate.

Following the demonstration I answered questions ranging from how to access old programs and files to security concerns in Windows 2000.

Provide Desk-side Support – 14 hours

After the presentation, I visited each staff member in person to help with specific questions or concerns. As with many offices, there was a broad range of skills to accommodate. Some Users had come from Windows backgrounds in other companies and were pleased to return to a Windows environment. Others had only ever known a Mac environment and verged on terror at the prospect of starting all over again with a new and unfamiliar operating system.

I took time to assess their individual needs so that I could provide service to even those who initially thought they didn’t require any support. For example, I showed some Users how to create mail rules to organize their email in Outlook, how to assign their favourite keyboard shortcuts to toolbars in Word and how to navigate and manage files in Windows.

I returned over several days to provide desk side support and re-iterate the initial presentation to those how had not been to the original presentation.

Design Corporate Logo 3.5 hours

An interesting spin-off of this contract was that the IT Administrator discovered that their corporate logo did not port over well from Macintosh to Windows and asked if I could redesign it.

My solution was to recreate their old logo using Adobe Illustrator and Photoshop and create both Web and print versions to suit all their needs. After one revision, they were pleased with what I created and the new logo now adorns their corporate letterhead and Website.

Conclusion

Although I have taken on more technically challenging contracts than this one, rarely have I been able to roll so many skills into one short contract. I welcome all other creative and diverse opportunities where my skills and abilities can be as well utilized.

And here’s what the client had to say

Thank you for providing [us] with Jason Hall’s services during their migration; the project is officially over. During the sign-off interview, [our IT Manager] said she was extremely satisfied with the work Jason did. (Despite me giving you such short notice!) [She] was particularly impressed with Jason’s ability to quickly resolve their logo migration issue. This would have been a huge problem for them to resolve but Jason did it within a day.

Thanks again for pulling the rabbit out of the hat. I look forward to working with you again.

My Favourite Writing Videos

[myyoutubeplaylist Vc2aSz9Ficw, x-5mIompIQ8, qn8VM8bJNjE, lQvsGZNU4UA, jwMj3PJDxuo]