Plain English

The Plain English movement strives to streamline, simplify and clarify written communications. Plain English encourages writers to:

> Use active voice with strong verbs
> Try to use personal pronouns
> Bring abstraction down to earth
> Omit superfluous words
> Write in the positive
> Edit long sentences.

Use active voice with strong verbs

Use the active voice with strong verbs to draw attention to actions and information.

Readers quickly understand sentences in an active voice because we typically think and process information this way. Sentences in a passive voice require extra processing as we convert passive forms into active. For example:

Active	A QA technician must sign off each report item.
Passive	Each report item must be signed off by a QA technician.
Passive with no agent	Each report item must be signed off.

You'll find many examples of "passive with no agent" constructions in most technical documents. Use this form when it doesn't matter if your reader to know who or what performs the action, or when you want to diffuse or authority or responsibility, as in:

It has been determined that to better serve out clients there will now be a $2 service charge for each transaction.

Another (bad) example:

The foregoing sample printout is intended to assist institutions using this report in understanding the report details that they will see on their reports.

To say the same thing in Plain English, make the voice active, give the sentence a strong verb, and throw out the filler words:

This sample printout shows report details you will see on your reports.

Remove nominalizations

A nominalization is a noun created from a verb that usually ends in -tion. It is usually less direct than a strong verb, and requires more support words. For example:

The team will make an evaluation ....
The team will evaluate ....

The task force made a determination ....
The task force determined ....

ACME must make an application ....
ACME must apply ....

Your writing becomes cleaner and clearer when you replace nominalizations with strong verbs. For example:

Before	There is the possibility of prior product manager approval of these costs.
After	The product manager might approve these costs in advance.

Before	ACME will have no ownership of the ancillary hardware.
After	ACME will not own the ancillary hardware

Before	The review committee will provide appropriate information to the shift leader ....
After	The review committee will tell the shift leader....

Thank you for your attention in this matter.

Homonyms (words that sound alike)

My husband and I would like to talk to you for a moment about homonyms, or, more pedantically, homophones and homographs (words that sound alike and words that are spelled alike respectively).

We know you don’t care about the actual terms. (We’ll let you in you on a secret: almost no one does.) But you do care about the concepts. Think of there, their and they're, for exmple.

Homonyms

Homonyms are words that sound the alike, but don’t mean the same thing. We have noted several abuses of the words there and their in documents recently.

There as an adverb or noun usually indicates a place or position, as in:
     There were a number of reasons for the protest, but the end result was the same.

Their is a possessive pronoun, or third person plural, as in:
     They picked up their chairs and hurled them from the rotunda.
They’re is a contraction of they and are, as in:
     They’re feeling much better now.

Homophones

Words that sound alike. For example, piece (and peace) of mind. Giving someone a piece of mind (as in a piece of my mind) – is not the same as giving that person peace of mind (as in a peaceful mind).
Other common homophones include:

And/End
What with one thing and another, …
He reached the end of his rope.
Buy/By/Bye
Buy it now.
By the time you read this letter…
Bye for now.
Threw/Through
She already threw the cat.
She passed through the hall.
Your/You're
Please include your postal code.
You’re one of a kind, baby.
Homographs
Words that are spelled alike, but with different meanings and - often - origins, as in bow (to a lady) and bow (on a gift-wrapped present).

Homophones are much less misused than homographs (except, perhaps, by loquacious queens).
Rules of thumb

• Don’t count on your own proofreading to catch homonyms and homophones – you’re mind sees what it expects to see, not what you wrote. And never count on an electronic grammar checker to find accidental homonyms and homophones. Even the best word processors are only marginally successful.
• Context is the only way you can tell if a word is being used correctly, and no electronic grammar check is foolproof.
• Always ask someone else to review your correspondence, email and other documents before distributing them.

Thank you for your time and attention in this matter.

Back to Contents

Foreign words

My husband and I would like to talk to you for a moment about foreign words and phrases appearing in your correspondence, documents and guides.

Foreign words, like foreign-born nationals, usually become indistinguishable from native ones over time, just like Philip. Who thinks of Prince Philip as "that Greek boy from Corfu" any more?

In the same way, nobody thinks of bungalow, canyon, potato or pajamas as foreign. They have become naturalized English words and no longer require italicization. Ad hoc has become naturalized while a priori probably has not and should be italicized (better yet, don't use pretentious phrases like a priori at all!)

• Please note that ad hoc is composed of two separate, unhypehenated words.A single mistake like ad-hoc can ruin the professional appearance of any written communication.

Please refer to an authoritative dictionary such as Oxford (not the sad little online dictionary that comes with Word) to ensure correct spelling of foreign words.

Set unfamiliar foreign words and phrases in italic for emphasis. Using italic doesn't mean your readers will understand them any better, but it does alert them to their presence.

In the financial services industry, you are advised to err on the side of caution: assume your readers are unfamiliar with ALL foreign words and phrases, except perhaps percent and ad hoc.
Rules of thumb:

• Italicize most foreign words and phrases.
• Don't italicize familiar or 'naturalized' foreign words and phrases.
• Don't italicize proper nouns designating:
  * foreign persons (such as il Papa and la Contessa),
  * foreign places (such as Gare du Nord and Firenze), and
  * foreign institutions (such as Surete and Interpol).
• Use a dictionary to confirm the spelling of foreign words and phrases.

Thank you for your time and attention.

Back to Contents.

Number and tense agreement

My husband and I would like to talk to you for a moment about number and tense agreement. There have been times in life when these were the only relationships in which there was agreement.

Number agreement

Every noun-verb relationship should agree in number. That is, in any given sentence, a singular noun takes a singular verb and plural noun take plural verbs.

Note, for example, the following:

A weekly status report is on the table.
All weekly status reports are on the table.

One attachment accompanies this letter.
Ten attachments accompany this letter.

Groups of related sentences should share number agreement. That is, if you refer to something as plural at the beginning of a paragraph (users, WTS items, challenges, …), you should still refer to them as plural at the end.

Tense agreement

Every sentence in a single body of text (letter, report, email, …) should share the same tense (sense of time).

If you're writing in the present tense, use verbs in the present form (come, see, conquer); in the past tense, use verbs in the past form (came, saw, conquered.)

This rule is not hard and fast: sometimes you have to mix past and present, or present and future, tenses. The following sentence mixes tenses:

If you enter a future date, the system will display an error message.

And, alas, these images also mix past and present:

As a general principle, tense consistency makes your writing clearer and easier to read.

Use the simple present tense (call, copy, export, email, enter, read, …) as much as possible because this is the most common form of speech and therefore the most familiar to your readers.

When you use the simple present tense, your readers are more likely to concentrate on what you say rather than how you say it – the message, not the medium.

Rules of thumb

• Use singular verbs with singular nouns and plural verbs with plural nouns.
• Use the simple present tense in most of your business writing.
• Use the same tense for all sentences in a single body of text.

Thank you for your time and attention.Back to Contents.

Hyphens and dashes

Don’t dash – unless you have to

My husband and I would like to take a moment to speak to you about dashes and hyphens – those overworked particles of punctuation so liberally sprinkled throughout your communications. You may know hyphens as en dashes (shorter dashes) and dashes as em dashes (longer dashes) or double dashes.

Older readers may remember pre-computer days when em dashes were typed as --. Many use en dashes exclusively, but this variance may be overlooked provided that whichever pattern is used is at least used consistently throughout a single document.

Hyphens

Use hyphens (en dashes) as part of a compound word (as in ninety-nine Luftballons), or between multiple modifiers if they aid understanding (as in three quarter-hour sessions). Do not insert spaces before or after a hyphen.

Usage conventions are in a state of constant flux. Recommendations vary from grammar book to grammar book, and over time. For example, database started out as two separate words (data base), temporarily became hyphenated (data-base) and now regularly appears as one word (database). Similarly, the hyphens in online and email are in the process of disappearing now. While We still see on-line and e-mail from time to time, online and email are much more common.

Grammar moves in the direction of simplification: if the punctuation isn’t necessary for understanding, it eventually gets dropped.

>   Please note that Latin phrases are not subject to the vagaries of English usage. Latin is a dead language and therefore cannot evolve or change. For example, the Latin phrase ad hoc has been, and remains, two separate words. There is no such word as ad-hoc (or adhoc for that matter).

If in doubt about whether or not to use a hyphen, please don’t rely on the language, spell check, or grammar functions on your word processing program to give you the answer – these functions are spotty at best, and occasionally out and out wrong. Once again We observe that English is not a forte with Americans, programmers, or American programmers.

Refer to an authoritative dictionary (such as Oxford), or talk to someone in Documentation or Corporate Communications about conventions currently in use in your organization. When in doubt, corporate style guides trump personal preference.

Dashes

Use dashes (em dashes) as part of a sentence to indicate a break or shift in a sentence – like this.

Some organizations recommend that writers insert a single space before and after a dash used in a sentence, although many other authorities advise against inserting these extra spaces.

Use a pair of dashes -– like the ones you see here -– to indicate a subordinate clause in a sentence that could have been punctuated with commas or parentheses (curved brackets).

Whether you choose to use commas, dashes or parentheses depends on how much of a break you mean to indicate.

• Commas, the least intrusive, don’t draw much attention to themselves.
• Dashes – more obvious forms of punctuation – indicate an inserted element.
• Parentheses (short of a period) are the most emphatic break of all. 

Rules of thumb

• Hyphens should be used in compound words (and between words used as modifiers) as often as necessary to clarify meaning.
• Dashes should be used sparingly to indicate a strong break or shift in a sentence. A dash is not a catch-all punctuation mark replacing commas, colons, semi-colons and periods.

•  Whatever pattern you choose to adopt, use that pattern consistently throughout a single document or series of documents.

Thank you for yout time and attention.


Back to Contents.

The Queen's English

Contents

Active and passive voice
Compound verbs
Hyphens and dashes
Number and tense agreement
Plain English: Active voice and strong verbs
Plurals and possessive plurals

(New topics are added monthly.)

Active and passive voice

Puppies, partners and patterns of speech can be active or passive. Many of us already know as much as we need to know about puppies and partners, so let's talk for a moment about patterns of speech.

Active constructions

Active constructions clearly identify who or what performs an action. The following sentences are active with clear subjects and actions (verbs):

1. (You) Press [Enter] to accept the default option.
2. The system displays the main menu.
3. The night shift supervisor at your institution must complete the attached signoff sheet. 

This simple, direct form of expression works best when you give directions, procedures, lists of instructions – in fact, any time you need to communicate specific, unambiguous information.


You should always write directions, procedures and list of instructions in an active, direct form. Include a clear subject and (present tense) verb for every step or direction.

Passive constructions

Passive constructions, on the other hand, are less clear about who does what, and may be subject to misinterpretation. The following sentences are passive with tenuous links between the do-er and the deed:

1. The default option is accepted when [Enter] is pressed.
2. The main menu is displayed.
3. The attached signoff sheet must be completed.
4. Two files were added to the directory. 

These constructions are not wrong per se, just more vague than active constructions. Passive constructions are uncommon in ordinary speech, but much more common in print.


Passive constructions sometimes seem to be the norm in scientific, engineering and computer circles. And passive constructions, especially the impersonal passive (it has been decided…, a policy has been implemented …), are common in government- and management-related documents (not any specific management, of course – just management in general) for a different reason. This voice is sometimes appropriate too.


The impersonal passive voice deflects responsibility, and diffuses responsibility, blame or guilt. Using this voice may be appropriate, for example, when you have to communicate unpleasant information. For example:


It has been decided that our increased costs should be shared equally among the system users.


Writing this way makes it difficult (if not impossible) for readers to identify the decision makers, and this might be a good thing.

 Rules of thumb

• Use active constructions in client-related directions, procedures and lists of instructions in order to simplify directions and avoid ambiguity.
• Limit passive constructions and the impersonal passive voice to communications in which you specifically want to be vague about responsibility for a statement.

Thank you for your time and attention.


Back to Contents.

Backup is not back up

My husband and I would like to speak to you for a moment about the misuse of compound words as verbs - words such as backup, logon and setup.

You have, for example, seen back up and backup used interchangeably to mean the same thing. We have come to believe that, for many, the decision to use one form or the other is as much a product of guesswork as of grammar.

Rule of thumb

If it’s a verb, make it two words. If it’s an adjective (or noun), make it one.

For example

Back up (v)	Back up the carriage, Philip. We observed a parking space in front of that chip shop.
Backup (adj)	Bring Us Our backup sceptre. We believe the batteries in this one have expired.
Log on (v)	Power up your system before you log on.
Logon (adj)	The system features a quick and easy logon routine.
Log out (v)	Manually log out of the system before you sign off.
Logout (adj)	The logout process is described in detail in Appendix A.
Set up (v)	Please set up a separate account for each RRSP product.
Setup (adj)	Complete the setup procedure before running the system.
Sign on (v)	Sign on to the system to display the main menu.
Signon (adj)	The system prompts you for a name and password during the signon process.
Stand by (v)	Stand by your man. Show all the world you love him.
Standby (adj)	The system functions in standby mode under certain conditions.

Thank you for your time and attention.


Back to Contents.

Queens v Queen's v Queens'



My husband and I would like to talk to you for a moment about s, 's and s' - grammatical constructions that sound alike but mean something quite different.

Note, for example, the following differences: 

Queens  = two or more female monarchs

Queen's = something belonging to one female monarch, or the Queen is or the Queen has

Queens' = something belonging to two or more female monarchs

s

• Most English words simply require an appended s to become plural (such as two queens). With only two or three score annoying exceptions (such as corn, sheep and men) this principle applies to virtually all nouns and pronouns. Irregular nouns, like irregular bowels, are difficult to discuss, so We won't.
• Most words already ending in s simply require an appended es to become plural (such as two princesses).
• Some companies advise writers to use an appended s to pluralize initialisms (such as all ABMs, both PIFs) and numbers (such as 90s).

's & s'

• Add apostrophe s ('s) to most singular nouns and pronouns to mean something belonging to one person or thing  (ACME's policy, today's schedule, …).
• Add an apostrophe (') to most nouns and pronouns pluralized with an s to mean something(s) belonging to more than one person or thing (managers' perks, timesheets' totals, …).

Its and it's

• Use its to indicate possession, as in the dollar continues its stellar performance.
• Use it's as a contraction of it is (or it was), as in It's raining men.

Rules of thumb

• For most nouns and pronouns, add s to mean more than one.
• For most nouns and pronouns ending with an s, add es to mean more than one.
• For most singular nouns and pronouns, add apostrophe s ('s) to mean something belonging to one person or thing.
• For most plural nouns and pronouns already ending with an s, add an apostrophe (') to mean something(s) belonging to more than one person or thing.

Thank you for your time and attention.


Back to Contents.

A word about older writers

The market for writers has been pretty grim the past few years, and even grimmer for someone on the far side of 45.
.

And while it sometimes seems that all the jobs are going to new faces with freshly minted degrees, the reality is that we're all flailing in an increasingly crowded job-pool. It's just that older – no, let's say more mature – job seekers face additional hurdles.

.

We are all to some degree judged by out appearance and how we present ourselves, and while we can put our best foot forward, we can't really hide our years of experience. Our faces and our resumes give us away. And for some employers, this maturity is viewed as a handicap - and that's a shame, because older workers can bring a wealth of skills, experience and talent honed and improved over long years in the business world.

.

Talent and ability are not the sole prerogative of the young and the comely. Older workers could not have succeeded for as long as they have unless they possessed them too. Most mature workers bring with them long histories of successes.

.

Older workers are in it for the long haul. They have successfully navigated a lifetime of deadlines, changes, disruptions and adaptation to be where they are today. They are like long distance runners in the middle of a course: they've successfully navigated many obstacles to get this far in the race, and they'll navigate many more before they reach the finish line.

.

Angry clients. Bad bosses. Buyouts. Corporate mergers. Deaths in the family. Layoffs. Lost data. Marriage breakups. Missed deadlines. New software. Office politics. 'Paradigm shifts.' Personality clashes. Platform migrations. Serious illness. Strikes. System crashes….

.

A full list of the 'challenges' they've overcome would frighten Odysseus – and yet most mature writers have successfully navigated these difficulties and more during their careers. Experienced writers have been tested and have proven their mettle while newer writers are often encountering these experiences for the first time.

.

To stay competitive, mature writers must keep their skills current and saleable. This means constantly learning about new software, new delivery systems and new approaches to documentation. It means networking with other writers, reading about and using new technologies and tools, and staying abreast of current trends and developments.

.

Mature writers must also stay flexible and remain open to change. The market is not what it was 10 years ago or even five years ago, and writers must adapt to succeed. They must stay curious about developments in the field, and be receptive to new approaches, working relationships and expectations.  It's not enough to know grammar, punctuation and style conventions any more – if it ever was. Budgets are smaller, deadlines are tighter and expectations are greater, and we have to work smarter to stay on top of these changes.

.

Mature writers must also remain upbeat and project optimism. Face it – no one's succeeded in the business world for long by accepting failure. A 'can do' attitude and a willingness to find workarounds and fixes go a long way to creating future successes too.

.

Check your doubts at the door, put your best foot forward and emphasize your skills, successes and creativity. You've hooked the brass ring before and you can – you will – do it again.

Freelance writer

Among a certain class of Medieval European society, eldest sons inherited the father's estate, second sons given to the Church and superfluous sons left to fend for themselves.

To encourage third sons to fly the nest, Dad forked out for a horse, armor and weaponry, and broadly hinted that it was getting pretty crowded around the castle these days and maybe the boy might want to get off that d@mn couch and earn his own bread and butter.

With Dad's knightly kit and nightly encouragement, superfluous noble-born sons could become 'lance knights', a term which meant much the same in the Middle Ages as 'hired gun' does today. A mercenary, if you will.

It comes as no surprise to learn that lance knights were identified by their lances - long wooden shafts with a sharp metal head. And lance knights were free in the sense that they weren't bound to the service of any one state, king or lord (a condition slaves, vassals, chattel and servants could only dream about).

Hence they were free lance knights. (A pedant might say they were really free lance-knights or free-lance knights, but that's a question best left to pickers of nit.) These knights could be hired by any King Thomas, Richard or Harry to work as escorts, guards and soldiers.

In the Twentieth Century, freelance (OED treats it as a single word) has come to mean any self-employed worker who is not committed to a single employer long term.

Many technical writers work freelance, a role which is for some a matter of choice (a freedom gladly embraced) but for others is one of necessity (a freedom thrust upon them by markets reluctant to hire in uncertain times).

Freelance writers are sometimes called independent writers, but that term carries none of the picturesque knightly connotations.

Documenting procedures

Whether you're managing a documentation project or tasked with the actual
writing, you'll need to address key issues to efficiently document, update or convert your operational (task-oriented) procedures.

This session surveys these issues:

• Elements of a procedure
• Elements of a procedures manual
• Why document procedures?
• Choose an appropriate format
• Use existing resources
• Negotiate realistic deliverables
• Estimate costs and effort
• Identify and write to your audience
• Repeat simple patterns in your writing
• Carefully review and proofread your manual
• Implement sign off and sign-off sheets

DOCUMENTING PROCEDURES 00

01 Elements of a procedure

A procedure is:

• A way of proceeding, usually a mode of conducting business or a legal action
• A series of actions performed in a specific order or manner

A documented procedure typically includes:

• A descriptive title or access point
• A clear sequence of actions and responses to those actions

A documented procedure may also include:

• An account of the output or result
• Warnings about potential problems or error conditions
• One or more links to related topics  

'The truth is out there' (X Files)

The most critical component of any documented procedure is complete, accurate and up-to-date information. All other components – platform, organization, layout, formatting – are secondary. If you take away nothing else from this session, remember that to efficiently document procedures you must:

• Keep the project as accurate as possible
• Keep the project as simple as possible
• Keep the project as short as possible

DOCUMENTING PROCEDURES 01: Elements of a procedure

02 Elements of a procedures manual

A procedures manual typically includes the following elements:

• Unique name, version, and publication date
• Standardized page or screen layout and formatting
• Standardized page numbering scheme (print format) and chapter/section/topic naming scheme (print and electronic formats)
• Table of contents
• Introduction and explanation of who this manual is for and where other information is available
• Procedures organized in some logical fashion (e.g. by function group [cataloguing procedures, overnight runs, circulation reports, etc.], in order of performance, alphabetically by name, etc.)
• Index or other search tools

In practice, a procedures manual often becomes a junk drawer for all types of documentation of questionable usefulness and reliability. 'Just put it somewhere in the Procedures Manual' becomes the lazy solution to identifying what and where information should go. While it may work in the short term, it builds up trouble for the future – especially if and when the manual is reviewed, updated or revised.


DOCUMENTING PROCEDURES 02: Elements of a procedures manual

03 Why document procedures?

In many organizations, procedures are known only to the people who use them and are never documented, or are only casually documented.

Managers and peers may be aware of some or all of these procedures, but without a single reference point, no one can really know for sure.

Documenting procedures:

• Centralizes procedure-related information in a single location and format
• Captures and preserves information that might otherwise be lost as users change position within your organization or leave
• May be legally or contractually required (for union agreements, audits, offsite backup, etc.)
• Allows you to test validity of current procedures and recognize:
  - Better or more efficient ways of doing these procedures
  - Obsolete or out-of-date procedures
  - Gaps in current procedural documentation
• Helps ensure standardized performance of procedures and reduce procedural errors
• Provides a checklist for users when they perform unfamiliar activities
• Creates workarounds for systems that don't work, or no longer work the way they used to (e.g. 'send weekly timesheets to the fourth floor HP printer', or 'submit vacation requests to your supervisor by email, not on paper')
• Helps users identify and successfully complete new or revised procedures
• Potentially reduces supervisor intervention for simpler procedural issues if users are encouraged to first review procedural documentation before requesting help
• May reduce training and retraining time
• Becomes a starting point or supplement for other documents such as training and reference tools or troubleshooting instructions

DOCUMENTING PROCEDURES: 03 Why document procedures?

04 Choose an appropriate format

The litmus test of a successful manual is whether or not users can find what they need when they need it. Information must be accurate and up-to-date, but even the best information is ineffective if users can't quickly find exactly the right information required to complete the task at hand.

Format plays a significant role in determining how quickly users can access information. Where will your document be used? For what purposes?

Consider emergency exit instructions for example. Simple, often visual, directions are typically posted at eye level by stairwells and elevator lobbies so they can be easily accessed in an emergency. Emergency directions online or in a manual are less accessible, and less useful, during a real emergency, but may be helpful when training new staff or reviewing and updating current procedures.

Main format options include:

Print formats 

• May be as complex as a printed guide or as simple as a sheet of paper, a quick reference card, a keyboard overlay or laminated wall chart
• Can be generated by a very large pool of resources, both in-house or via contract
• Have well-understood access points (such as contents, headings, index)
• Are generally robust, durable and portable
• Usually entail significant post-documentation production and distribution costs
• Typically require significant effort and cost to update
• Often require significant effort to convert to electronic formats

Electronic formats

• Include help systems, Content Management Systems (CMS), Portable Document Format (PDF) projects and even online Word files
• Generally need writers or other dedicated resources with specialized knowledge to produce and manage
• Are well-understood by some users, but often unfamiliar to most
• May require training time for users
• Require access to a computer, and sometimes specialized software, a web connection and possibly a printer
• As a rule entail almost no post-documentation production or distribution costs
• Typically necessitate less effort and cost to update and easily accommodate small, frequent updates
• Entail less effort to convert to other electronic formats

DOCUMENTING PROCEDURES 04: Choose an appropriate format

05 Use existing resources

If you're tasked with documenting procedures on a limited budget or with tight deadlines, it's in your interest to use existing resources and materials. The most expensive move you can make is to write in isolation.

As much as possible, you want to:

Build on what others have done before you

There's no point in duplicating effort if you don't have to: recycle existing documentation and piggyback on the work of others.

• Were there earlier efforts to document procedures?
• Have other departments (such as human resources or training) or teams produced procedures manuals you can use as models?
• Are the people who worked on that project or similar projects still on staff and available for input or help in other ways?
• Does useful information exist elsewhere such as emails or faxes?
• Even manuals or other documents from software and hardware vendors may be used under certain circumstances.
• Is there a corporate, institutional or departmental documentation style guide? If not, consider The Chicago Manual of Style (Chicago: University Press) or other published guide.
• There are many writers' guides on the market – check your your collection, or talk to your local bookstore.

 Use current, familiar software

Unless you are given a specific mandate to use a new or unfamiliar package or format, seriously consider using current well-understood software.

New software often entails significant learning curves, extra time for fixes and conversions, and all-too-often come with bugs which will drive you crazy.

Licenses are required for each workstation using the software – licenses you have to buy.

And your users may require training or special conditions (such as access to the Internet) before they can use the product.

Identify other resources in your organization who can help you identify, document, test and produce or publish

Are there others on staff who have writing experience? Subject Matter Experts (SMEs)? Others who can sign off on accuracy of information (such as supervisors, training department or human resources personnel)? Can you borrow resources from elsewhere in your organization?

If you have tight deadlines and sufficient funds, consider bringing in professional outside resources to help, or outsourcing the project:

• Hire a short-term contract writer through your human resources department
• Contact one of several local colleges that offer student placement or student co-op programs
• Talk to a third-party vendor who specializes in technical documentation? Arrange a contract through an employment agency
• Post a position or contract on the Society for Technical Communications (STC) online job board (http://www.stcwestcoast.ca/)

DOCUMENTING PROCEDURES 05: Use existing resources

06 Negotiate realistic deliverables

Delivering documentation that works is a snap when you've got unlimited time and resources, but delivering workable documentation with limited resources, time and personnel requires careful negotiation and planning.

Negotiating realistic deliverables is critical to the success of a project. Success is not determined by what you can you do, but what you have to do.

Identify the minimum you have to do to:

• Comply with contractual obligations
• Satisfy management's expectations
• Meet users' needs

Identify what has to be released first, and what might be put off to a second or later release

After you know what must be included in your documentation, can you narrow the initial release to a smaller subset? This is particularly important for novice writers, as multiple releases help you iron out the bugs in your documentation, production and distribution.

Consider documenting frequently reported problems, or those things that are most critical for your organization, first (correctly completing timesheets, restarting the system, defining corporate appeal processes, etc.)

If this is your first or second project, don't plan beyond 2-3 months into the future.

Prepare a documentation plan that outlines:

• Contents of the project
• Resources required to deliver this content
• Benchmark deliverables and dates
• (Optional) Information about elements moved to a second or subsequent release

Ensure that all parties with vested interests in the project agree to your documentation plan (signatures may be used to confirm assent)

DOCUMENTING PROCEDURES 06: Negotiate realistic deliverables

07 Estimate cost and effort

Before you begin writing, schedule a 1-2 week research period to determine what needs to be done, what resources you need to complete the project, and what the effort may cost.

If this is your first documentation project

You probably have little idea how long or how much effort it will take to complete a new project. To be fair, even experienced writers sometimes find it difficult to estimate, particularly if it's written on new software, in an unfamiliar field or different work environment

1. Establish a best guess of the number of procedures you need to document in the first release.
2. Budget 1.5 pages per procedure (simple procedures may require less, complex more).
   Number of procedures x 1.5 = Number of pages  
3. Assume you can document three pages per day and multiply your total number of pages from step 1 by 3 to identify the number of days it may take you to document these procedures.
   Number pages x 3 = Number of days
4. (Optional) Multiply the number of days in step 3 by the number of work hours in a day (typically 7 or 7.5) to identify the total number of hours hours it may take you to document these procedures.
   Number of days x 7 = Number of hours

If this is not your first documentation project

Refer to previous projects to estimate hours required to document a single procedure, your average number of pages per day, and time to complete similar-sized projects. If your organization uses timesheets or time tracking software, use these to help gauge time requirements.

1. Establish a best guess of the number of procedures you need to document in the first release.
2. Budget 1.5 pages per procedure.
   Number of procedures x 1.5 = Number of pages
3. Use past experience to identify the number of pages you typically complete in a day. Multiply your total number of pages in step 1 by this number to identify the number of days it may take you to document these procedures.
   Number of days x 7 = Number of hours
4. (Optional) Multiply the number of days in step 3 by the number of work hours in a day (typically 7 or 7.5) to identify the total number of hours hours it may take you to document these procedures.
   
   Number of days x 7 = Number of hours

Other factors and hidden costs:

 Not all documentation costs are immediately obvious. Other factors to consider include:

• Sometimes the procedures are new or are untried and you have to test and prove them as you write
• Occasionally coworkers holding crucial information are too busy to help or view you as a nuisance and refuse to help
• Sometimes the committees responsible for establishing procedures take longer than expected to come to an agreement, or repeatedly revise 'completed' procedures If you're using new software to document the procedures, there's learning time to consider, and the inevitable bugs and workarounds new systems require. Do other staff need to learn this software? Who will teach them, or troubleshoot for them?
• If you've opted to use a new format or platform, will users need software, hardware or other tools to read, use or access your project? Will users require training? Even converting existing documents from one platform to another (for example Word to web) takes a surprising amount of time due to inevitable formatting, layout and graphics issues
• Maintaining and controlling master versions and backups (both on and off site) take time and resources
• Are there other purchases and expenses: software licenses, memory, peripherals, scanners, discs, binders, tabbed dividers, photocopying?

Time tracking
Track time for duration of first project to help improve estimates on subsequent projects. Consider using a table or spreadsheet to track time spent on each element such as research, writing, editing and producing.

Give each procedure a separate identifier, and track elements in 15 minute increments. Track times for everything related to the project, including meetings, writing, editing, getting sign off signatures, compiling, distributing copies, etc.

DOCUMENTING PROCEDURES 07: Estimate cost and effort