Writing Standards & Copywriting for Your Company

This guide outlines the best practices and standards for writing out documentation using an actual company style guide as an example.

Jump To: Introduction | Spelling & Grammar | Capitalization | Proper Pronouns | Sentence Structure | Miscellaneous Sentence Structuring | Punctuation | Hyphenation | Parentheses | Brackets | Quotation Marks | Forward Slash Spacing | Ampersand (&) Usage | Common Conventions | Conclusion

Introduction

Whether creating a business document or coding for a website, there are company (and universal) standards and best practices regarding writing that must be adhered to. The following document is meant to guide writers and developers to creating better content by outlining writing standards and best practices.

This guide will also include how to keep a document clean and manageable, including how to properly save and maintain images.

Spelling & Grammar

MS Word Language Setting

1. Always check for spelling using the software’s spell-checker. If the software you are using does not contain a spell-checker, copy the information to a program that contains a spell-checker, like Microsoft Word or have someone else check for errors.

2. Be sure your software’s language settings are set to the language of your region (example: English - America). In Microsoft Word, you can see the language setting in the bottom bar. If you are editing a client’s document and their standard is to use another language type (example: English - Canada), switch to that type before checking for spelling and grammar.

Capitalization

Your writing standards guide should include when to capitalize, and when not to. The following is an extensive list of rules regarding capitalization...

Capitalization should only be used for the following reasons:

1. The beginning of a sentence or quotation.

A user might say, “Let’s create a ‘save’ button.”

1. Use capitals for proper nouns. Capitalize the names of people, specific places, and things. Notice the words “bridge”, “system”, “modules”, and “help guide” are not capitalized. They are things, but not the specific names of things.

The bridge is called Monument Bridge. The person’s name is Michael. The system is called the Case Management System, which contains modules, like the Intake Page. The CMS also has a help guide.

*Remember that proper pronouns are given names of people, places, and things:

1. If we say, “Head to the page to perform an intake,” we are not addressing the page itself; we are addressing the action of doing an intake. This is lowercased “page” and “intake.”

2. If we say, “Head to the Case Intake page,” we are using the page’s name, which is “Case Intake”. This is correct.

3. If we say, “Look at the Case Intake Page,” with a capital “Page”, we are incorrectly adding assuming the page’s name includes the word “Page”. The page’s name is “Case Intake”; it is a Case Intake page.

Terms (or software, products, and concepts) we create as a company may be capitalized (Portal, or Module for example). When capitalizing our own terms within a document, it is best to inform the reader that the term will be capitalized the first time it is used. Do not capitalize general words that we already understand as regular nouns (see “login” and “password” in the example below).

1. Users can access the system through our initial interface, called a Portal. When the user accesses the Portal, they do not require a login or password.

2. Users access the Portal, and they do not need a Login or Password.

(Notice “Portal” in the incorrect version was not referenced beforehand. To someone who isn’t aware of our terms, like a prospective client, it appears as though we have improperly capitalized the word)

1. Capitalize titles when they are on the signature line of a letter, when the title comes immediately before a name, or when the title replaces the use of a name (i.e., a title used as a direct address). Notice when “Father” is capitalized since it replaces the name, but “my father” is not capitalized.

Both Misses Adams and President Smith went to the park. She and the president spoke with Father, but my father didn’t want to speak with them.

1. Capitalize directions only when they refer to specific regions.

Our newest client is in Northern Canada. Drive toward the northern district until you get there.

1. All large words in the titles of movies, books, and other publications should be capitalized, while all small words (a, an, the, but, and, if, as, or, nor, to name a few) should not be capitalized unless they are the first or last words in the title. Below, note capitals of small words remain after the colon, as it behaves like it is in the beginning of a sentence.

You should watch the documentary, Wal-Mart: The High Cost of Low Price, and then read How to Win Friends and Influence People.

1. Capitalize words derived from proper nouns. In the following example, English is capitalized—it is derived from the proper noun England. Math is not capitalized, because it is not derived from a proper noun.

I like English, but math is my favorite subject.

1. Capitalize when two or more sentences follow a colon.

Known system restrictions: The system cannot currently talk back to the user with the voice of an automated assistant. This includes both the desktop and mobile version.

1. Do not capitalize if you are writing a list, or if there is only one sentence after the colon.

Page names: intake, investigation, reports, templates

Known software limitations: there are none.

Proper Pronouns

A proper noun is a noun that identifies a single entity, and is used to refer to that entity (such as Toronto, Lenovo, Deborah, or Microsoft) as distinguished from a common noun, which is a noun that refers to a class of entities (city, computer, person, corporation). be sure your company defines its proper pronouns in the document, including names for its software and products.

Crime Prevention System

Tire Chain

Audit Log (when addressing the master document all auditors use; not audit logs in general)

Common nouns must remain lowercased:

user audit log (when addressing the function of creating a record of sequential events, not when referring to a master document)

system

audit log (when addressing the function of creating a record of sequential events, not when referring to a master document)

Note when lowercase and uppercase terms are used below. A class of entities is written in lowercase, while term that is one specific entity (or specific entities) is uppercased.

Some users will see a different login page. This is designed with the User in mind.

The Master Template was used to create this document. Some templates require a landscape version.

Sentence Structure

Run-On Sentences

A run-on sentence is one with two independent clauses (complete sentences) that are connected improperly. A comma-splice occurs when two otherwise complete sentences form one sentence after a comma is added. The danger of run-on sentences is that too much information is being thrown at the reader at once. Readers can efficiently keep 2-3 conjoined thoughts in their heads at one time: this = that, or this + this = that.

Keep sentences concise, and use only 1-2 conjoining words (of, and, but, with, or, etc.). Aim to be straight-forward, with clear objectives and solutions. A run-on sentence creates a kind of complication that does not conform to our mission statement and values.

Example of a run-on sentence containing to a lot of information (note this paragraph is all one sentence). This sentence contains multiple commas, and conjoining words like “to”, “and”, and “or”:

We have reviewed the RFP entitled “University of Saskatchewan Student Database (USSD)” and believe that the Company X's Data Management Solution (CX-DMS) will deliver all the goals and requirements to replace or better integrate many of your existing IT solutions with an enterprise solution, to simplify the current, complex systems environment for users, break down silos in process management, and help to eliminate errors from poor access to information.

Example of breaking up the sentence to help readers:

We have reviewed the RFP entitled “University of Saskatchewan Student Database (USSD)” and believe that the Company X – Data Management Solution (CX-DMS) will deliver all your goals and requirements to replace or better integrate many of your existing IT solutions. Our solution will simplify the current, complex systems environment for users, break down silos in process management, and help to eliminate errors from poor access to information.

Correcting a run-on sentence:

1. Use a period to create smaller sentences.

2. Use a semicolon to create two independent clauses that are related: “I love to create style guides; I would create one every day if I had the time.”

3. Use a comma and a coordinating conjunction (like and, or but). Use only one per sentence if possible. These commas are different from listing commas like this, this, this, and this.

4. Be sure to keep one complete thought to a sentence. Do not explain or show multiple ideas within one sentence.

Sentence Fragmenting

A sentence fragment is a string of words that does not form a complete sentence. Usually this is due to a missing component that would otherwise complete the sentence. Be sure to check that sentences express complete ideas.

Shows no improvement in the system.

The system, which is in version 4, with a Bootstrap framework.

Miscellaneous Sentence Structuring

Acronyms and Short-Forms

When a new term is introduced that can use an acronym, add the acronym in parentheses. The full term is not needed again, unless it is used in a sentence.

The Company X Data Management System (CX-DMS) is a robust and highly configurable system. The CX-DMS runs in any updated browser. This can be offered in a Software-as-a-Service (SaaS) model. CX-DMS is fully compliant with accessibilities.

Our system is WCAG approved and is A.C.A. compliant. It runs on ITZT systems through ATR-RE service standards in a C.M.M.T. environment.

The example above was created with false information using non-existent terms. It shows that the reader will not understand every term; thus, we have to define them first.

When to use periods in an acronym:

There is no single rule to determine if periods should go between letters. Use these pointers as a guideline:

1. If an established preference is made, stick to that preference:

NATO, North Atlantic Treaty Organization

Washington, D.C.

CPU, URL, DVD, etc.

1. Be consistent within the same document. The term for Company X's Data Management System does not use periods (CX-DMS), so stick to that system when possible:

WCAG

S.a.a.S.

Use PM in capitals, or m. lowercased with periods, preference being the former

While acronyms often abbreviate by using the first letter in each word of a phrase, short forms abbreviate using the first few letters of one word, followed by a period.

Always use a period with short forms. Example: Mon. (Monday), Jan. (January), Ave. (Avenue), i.e. (id est = in other words), e.g. (exempli gratia = for example), etc. (et cetera = and so forth). See “Using Vague Enders” on page 7 below regarding these terms in bold.

Using Vague Enders

Refraining from using terms like “etc.” when providing examples within a sentence that does not contain parentheses. It comes off informal and conversational (that is to say, one might use it when speaking).

Refrain: Our modules include APIs for most functions like Case, Project, Location, Client, Document, Activities, Events, etc., and they are customized for each customer.

Better (place in parentheses): The module includes APIs for most functions and data entities (like Case, Project, Location, Client, Document, Activities, Events, etc.), and they are customized for each customer.

Best (pick a few strong examples): The module includes APIs for most functions and data entities like Case, Project, or Client, and they are customized for each customer.

Tenses

Keep to one tense within a document section — past or present. Depending on the document, a tense should be chosen for the whole file; however, there will be many occasions when the tense needs to be changed. Be sure to keep the tenses straight within paragraphs, or lists.

We are committed to the following timeline: - Updating Schedules - Assign tasks - Completed assignments

The example above uses the present-tense “updating” with another present-tense “assign” (which should be “assigning”). The past-tense “completed” does not match the other bullets either.

We are committed to the following timeline: - Update schedules - Assign tasks - Complete assignments

In the example above a tense was chosen (not to add “ing”), and the remaining list conformed to that tense. Note that present-tense was used, but later in the document a past-tense list can be created. The author could be talking about past accomplishments, which would require a past-tense list, but later about future goals and approaches, which may require present-future tense lists. It is acceptable to have different tenses in one document if the context necessitates it.

Punctuation

Bullets and Numbering

Use bullets when a list does not require sequencing. Use numbering when a sequence, like steps in an instruction guide, is necessary. Company X also uses checkmarks and X’s for Do’s and Don’ts respectively. Each of these styles (bullets, numbers, checkmarks, and X’s) can be found in the styles panel.

Note: Use a Bullets Paragraph Style in Word rather than simply bulleting and tabbing a paragraph to better keep the document's format. Doing so will protect the line within a paragraph style. If the line is simply tabbed to create the effect, any changes to the style later may affect this line in a negative way.

Correct (using styles and proper tabbing):

1. This is a bullet

o  This is a secondary bullet

Incorrect (using the Tab key and Spacebar):

· This is a bullet

- This is a tabbed bullet

Punctuation with Bulleted Lists

1. Avoid using semicolons to segment a bulleted list. More on this below

2. Periods are not necessary at the end of bullet lists

3. Keep bullet points short. It is not best practice to write paragraphs within bulleted items. Try sticking to two lines or sentences, maximum

4. Number lists that need to be in sequence. A numbered list can be used if there are many items to be addressed, or the items match another sequence (such as a question and answer grouping)

If the items in a bulleted list are phrases or clauses with punctuation in them, a semicolon can be used at the end of each item. It should be noted that this format is considered “old style”, and they are mostly seen in legal documents. Avoid using semicolons to punctuate bulleted lists when possible.

If semicolons are necessary, put “and” (or, if logic dictates, “or”) after the next-to-last item in the list and a period after the last item. The items are not capitalized (except for proper nouns), and a period follows the final bullet point. Example:

1. Bullets with full sentences that include punctuation, like commas and periods, should have semicolons placed after the sentence;

2. Semicolons should be used when bullets are part of a longer list; or

3. Avoid semicolon usage altogether.

Comma Usage

Use commas to separate independent clauses when they are joined by any of these seven coordinating conjunctions: and, but, for, or, nor, so, yet.

We partner with Microsoft, but not Apple.

Use a pair of commas to isolate non-essential segments of a sentence. Non-essential means lower priority than the main point of the sentence; it does not mean unimportant facts:

Our solution, which requires no installation of software, is a robust system.

Use commas to separate three or more words, phrases, or clauses written in a series. Note that the final comma (referred to as the Oxford Comma) is necessary.

Pages include Intake, Audit, and Report

Pages include Intake, Audit and Report

The Oxford Comma

To say “Jared is the Editor, Template Guru and Marketing Assistant” assumes that “Template Guru and Marketing Assistant” is all one title, for one job. The addition of a comma corrects this: Jared is the Editor, Template Guru, and Marketing Assistant.

Use commas to separate two or more coordinate adjectives that describe the same noun. Be sure never to add an extra comma between the final adjective and the noun itself or to use commas with non-coordinate adjectives. Coordinate adjectives are adjectives with equal ("co"-ordinate) status in describing the noun; neither adjective is subordinate to the other.

You can decide if two adjectives in a row are coordinate by asking the following questions:

· Does the sentence make sense if the adjectives are written in reverse order?

· Does the sentence make sense if the adjectives are written with the word “and” between them?

If you answer yes to these questions, then the adjectives are “coordinate”, and should be separated by a comma. ere are some examples of coordinate and non-coordinate adjectives:

The system is a robust, configurable solution.

Mark’s vehicle is a large, black truck (“large” does not describe the color “black”. It describes the vehicle).

Mark’s vehicle is a jet black truck (“jet” further describes “black”. It does not describe the truck)

Use commas to set off all geographical names, items in dates (except the month and day), addresses (except the street number and name), and titles in names.

Birmingham, Alabama, gets its name from Birmingham, England.

July 22, 1959 was a momentous day in his life. Who lives at 1600 Pennsylvania Avenue, Washington, DC

Rachel B. Lake, MD, will be the principal speaker.

Hyphenation

Note the visual difference between hyphens (minus signs), m-dashes, and n-dashes. Each are described below.

Hyphen

-

M-Dash

—

N-Dash

–

Hyphens

A hyphen (-) is commonly used to combine words.

Hard-pressed

Three-tiered system

1. Hyphenate words that come before a noun and modify that noun as a single idea. Off-campus offices, and state-of-the-art design can be hyphenated.

2. When the idea comes after the noun it is usually not necessary. “Our offices are off campus.” Note that some established phrases are always hyphenated: “Our technology is state-of-the-art.”

3. Do not hyphenate words ending in “ly” (like “barely”) before the compounded word. “The system is finely tuned,” is correct. The wrong way to write this is, “The system is finely-tuned.”

4. Hyphenate times and dates describing a noun. “The two-month trials came from a three-year-old system.” But, do not hyphenate, “The project took two months.”

5. Hyphenate spelled out fractions. “We have two-thirds of our team working from home, and a third of the team working in-office.”

There are a few exceptions and other hyphenation rules. Well known expressions and nouns do not need to be hyphenated, like ice cream, and twentieth century, although they technically should. Follow the rules above, and if you are unsure about hyphenation rules, a quick online search should provide good answers.

M-Dashes

An M-dash (—) is commonly used to create a strong break in the structure of a sentence. M-dashes are particularly useful in a sentence that is long and complex, or in one that contains a number of commas. They are typically used in pairs like a parenthesis group, or they end a sentence. In this example they are used as a side note. Notice if the text between the m-dashes were deleted, the sentence would still make sense:

Our product is a robust, highly configurable system—as well as out-of-the-box ready—that works in a wide variety of ways.

A good rule of thumb is to reserve m-dashes for those places where the comma simply doesn’t provide a strong enough break. If a comma (or a pair of them) works, use it. Parentheses tend to downplay an idea; they suggest that the information in them is helpful but not necessary. M-dashes draw attention to the information they enclose or set apart. Typically, the writer is telling the reader that the information being set off by m-dashes is important.

1. Keep m-dashes attached to the words in a sentence.

2. Do not add spaces between an m-dash.

N-Dashes

An n-dash (–) is commonly used to separate numbers (like a phone number). Hyphens are acceptable to use for numbers instead of n-dashes, but it is not technically correct. Keep in mind whether the text is being used for coding, or as a document to ingest. If the text is for coding, n-dashes may not be recognized, and a hyphen should then be used. Note the n-dash in the phone number, (555) 432 – 1098.

Tip: Microsoft will automatically convert single (-) and double hyphens (--) between words and numbers to an n-dash if there are spaces in between them.

Parentheses

Parentheses separate ideas within a sentence, or they add secondary information that is not part of the same idea.

Keep in mind parentheses tend to convey less importance than m-dashes when placed in a sentence.

The Intake page—containing the initial fields to fill out—is particularly important.

The Intake page (containing the initial fields to fill out) is particularly important.

Notice the stronger emphasis and importance when using m-dashes. Parentheses act as “asides” while m-dashes convey information that is just as pertinent as the rest of the information in the sentence.

Use parentheses to clarify information:

The system passes accessibility standards (ADA and WCAG).

Periods are placed outside the parentheses unless the content within is an entire sentence.

We have clients all over Canada (Toronto, Calgary, and Victoria.)

We have clients all over Canada (Toronto, Calgary, and Victoria).

Punctuate correctly both inside and outside the parentheses.

Mark likes Star Wars (doesn’t he?).

Content in parentheses are not considered part of the subject within a sentence.

OCC (as well as CFS) are clients of Company X.

OCC (as well as CFS) is a client of Company X.

Do not use brackets; use parentheses. Brackets are used for special occasions.

The Report page is listed in the secondary menu.

The Report page (where the client can draw up reports) is listed in the secondary menu.

Brackets

Brackets are interruptions by the speaker or writer and should not replace parentheses.

The article quoted, “CX-DMS, which has just gone through its second major version , is gaining traction within the case management game.”

Tech reviewer, John Smith, said, “The system is robust and versatile .”

In the first example the writer is indicating an update to an old quote. The second example points out a spelling mistake the reviewer made, since the review needed to be quoted word-for-word. “Sic” means “thus” in Latin, which translates to, “this is exactly how the original text was written.”

Quotation Marks

The following are the rules for using quotation marks:

Do not use quotations for terms if italics or bolding can better emphasize them. Also consider if the term in quotations needs emphasis or singling out at all.

Warning: A word within a quotation can come off as though the term is a made-up name. Try removing quotation marks and see if the sentence still makes sense. If a term needs to be singled out as important, try applying italics or bolding instead.

The “My Accounts” search page allows users to search the active account files they “own” or “contribute to” through different parameters, including Account Status.

The My Accounts search page allows users to search the active account files they own or contribute to through different parameters, including Account Status.

Canadian grammar standards use double quotation marks (“ ”), and only use single quotation marks when a quotation falls within a quotation. European English primarily uses single quotation marks (‘ ’).

“Company X” reflects one of our company’s philosophies of being direct and keeping the  understanding of sophisticated solutions straight-forward.

Use quotation marks when directly quoting another.

Jared said, “Templates are my forte.”

Jared said his templates “are his forte.”

The reason the previous example is wrong, is because Jared would not have said his. He would have said my.

Do not capitalize the quote if it is continuing the sentence.

Jared said that the system is “easy to use,” and “available through all browsers.”

Place punctuation inside or outside the quotation marks depending on the logic of the sentence. Does the question mark belong to the sentence, or the object within the quotation marks?

Jared asked, “Do you have an updated browser?”

Would you agree that your data management system is “WCAG compliant”?

Above (first example), the question falls within the quotation marks. The second example is singling out the term “WCAG compliant”; however, the question began with the sentence.

Remember to use quotation marks sparingly. If the term can better be emphasized with italics or bolding, use those styles instead.

Forward Slash Spacing

There should be no spacing before and after a forward slash, as it creates uneven line breaks in paragraphs. When spacing occurs before and after the slash, a word processor like Microsoft Word could place the forward slash at the beginning of the following line, which is incorrect.

This is correct/right

This is incorrect / wrong

Ampersand (&) Usage

Avoid using the ampersand (&) character. An exception would be when using a direct quote that uses the symbol, or when writing the name of a company that has the symbol in its name.

Correct:

Checks and Balances

File your taxes at H&R Block

Incorrect:

Cheese & crackers

Common Conventions

Examples in your company's writing standards guide may include examples of common conventions. Example:

Use email, not Email, e-mail, or eMail.

Use standard phone syntax: (xxx) xxx – xxxx, where the area code is in parentheses, and a n-dash (number dash) is used between the remaining 3 and 4 block number set. Add spaces between the number sets, except within the parentheses. Microsoft Word should automatically change a dash to an n-dash if it is left between numbers.

Cleaning Up A Document

The following section focuses on cleaning up old / legacy documents, and removing often-missed issues.

Single Spacing After Periods

It used to common practice to add two spaces after a period with each sentence. This was a relic from the days of typewriters that has made its way into mainstream typing. Many still double-space after a period, however it is now considered incorrect. What’s more is that it can create odd and obvious spacing issues in paragraphs that are fully justified.

The Fix: Find all double spaces and replace with single spaces.

To replace all double spaces with single spaces:

1. Open the Find/Replace dialogue box by pressing ctrl + h.

2. In Find What, tap the spacebar twice.

3. In Replace With, enter a single space.

4. Select Replace All.

A dialogue box will tell you how many changes were made. You may close all boxes.

Find and Replace Box in MS Word

Remove Unused Styles

Styles can sometimes be copied over with copy/pasted text, or they can be added, and then aren’t used. To remove all unused styles, follow these steps:

Removing Unused Styles:

1. In the Styles Panel (shift + ctrl + alt + s to open), select Options…. A new panel will open up.

2. In the first drop down list select In Use to show only the styles the page is using.

3. Press OK.

Style Pane Options in MS Word

Styles Pane Right-Click Menu

4.  Select the arrow beside any style that does not belong.

5.  In the drop-down list, choose Select All # Instance(s). You will be taken to the paragraph or character being affected by the style.

6.  Change the style to the correct one. Do this for all instances.

7.  Return to the Style Options dialogue box (see step 1), and in Select styles to show, select Currently in Document. Press OK. Now the non-default styles in the document that aren’t being used will show up.

8. When selecting the arrow beside any style, it will tell you it is Not Currently Used if it isn’t applied to any lines. Select Delete (style name)… to remove it.

Styles Pane Right-Click Options

Image Control

When images are to be inserted into documents, a Style Standards Guide should be adhered to, but the following information should be applied:

1. Use Insert > Picture from Word’s ribbon. This will keep the file size smaller, and create less metadata clutter for Microsoft Word to sift through

2. When creating screenshots, select only the area to be captured. Cropping a large image still requires the full image to remain in the file and can create a large document.

3. Save, and then insert screenshots rather than copy/pasting them.

4. Do not copy/paste images, even screenshots, as they tend to clutter up the document’s hidden metadata and programming. This can create file lagging later on

5. Do not crop when capturing only what is needed in a screenshot can be done. A PDF image that is 2MB is still 2MB when it is cropped. This can result in large file sizes that can lag.

Images & Accessibilities

When creating a document, remember to include Alt Text so anyone with accessibility needs are included, and can understand what the image represents. Select the Alt Text option and type a sentence or two describing the image. Make sure to use proper spelling, capitalization, and punctuation as these texts are often used for text-to-speech reading.

Alt Text in MS Word

In Conclusion

Every company should have access to a writing standards guide (or have their own). Writing properly conveys professionalism, and each document should be given that professional touch.