Writing Guidelines

Write all documentation content using:

• Active voice, as it is stronger than the passive and is standard for technical and user
• Second person, with the pronouns you and It’s easier to read and makes it clear that the audience controls the software.
• Present tense whenever possible. Avoid the future tense, especially in

Definition Standards

Definitions of field names, database columns, and financial instruments walk a fine line between the specific and general. Definitions must be accurate in terms of general capital-markets usage while applying specifically to Canright Communications systems.

At the same time, the Canright Communications business audience knows capital markets and trading very well and does not need definitions of basic terms. Developers may need more guidance but generally have the same familiarity with securities-industry basics.

As in the manuals themselves, we are not teaching basic securities, trading, or technical concepts. We are providing guidance on what things mean in a Canright Communications context and making sure our audience can navigate the systems, follow the procedures, and understand the underlying business rules where appropriate.

This is easier to accomplish when definitions either are provided by subject-matter experts or are closely reviewed by SMEs. This is seldom the case, however, especially in projects that include hundreds of definitions.

In most cases, however, definitions are derived by technical writers from external sources  that may be misleading in terms of the context  of Canright Communication’s systems. It requires thoughtful research and writing to capture both the technical definition and the Canright Communications usage without insulting the reader or running afoul pf copyright law.

Guidelines and examples follow:

• Be careful of general economic definitions-even general  financial-services industry  definitions-from lnvestopedia,  Wikipedia,  or any other dictionary,  especially if the source is not specific to the securities  industry or trading. In many instances, what seems like a general financial services term is not the same in capital markets and trading, as the examples below
• Neveruse information directly from an external source like lnvestopedia. It is not permissible to cut-and-paste from any external source. That’s a violation of copyright law. All definitions should be based on multiple sources where possible. Even those based on a single source must be rewritten, including Canright Communications context where
• Check the Canright Communications Glossary. Many terms have been defined already and appear in the Glossary. Also check the DalaM art Daia Dictionary. Most of the definitions for that project were written according to the above guidelines. The dictionary has gotten good reviews from both developers and business analysts. Some of these  terms originated  from the Glossary  but many were written for the DataMart dictionary and only appear in this

The following examples illustrate some of the challenges in writing definitions and how to overcome them.

Examples.

– Bank Loan

A loan or a line of credit expended to a corporation from a traditional bank.

This seemed like a reasonable definition of “bank loan” until looked at within the capital-markets context. Here’s the correct definition: A leveraged loan, generally a credit package syndicated by major banks, traded as a fixed-income asset.

• Forward Rate Agreement Floating Rate Index Leg 1. An economic index that is allowed to move up and down with the rest of the market.

That isn’t exactly what an index means in this context, although the function is similar to the standard economic usage of the term “index”. Swaps and similar contracts generally are based on a standard interest-rate or currency index, such as Libor, not a general economic interest. It may be 3 month Libor in EUR, 6 month Libor in EUR, 1 month Libor in USO, etc.

A better definition for the above term is, ‘The interest rate index on which the FRA’s floating rate is based, e.g. 3 month Libor in EUR, 6 month Libor in EUR, 1 month Libor in USO, etc.” That definition is accurate, assumes that the traders or middle-office staff know what they are doing, and doesn’t put Technical Communications in a position of explaining how an index works.

• Forward Rate Agreement Payment Date Adjustment Business Center. The adjusted date on which a declared stock dividend is scheduled to be

That one is problematic because many of these terms vary depending on the financial instrument. In this case, the word “dividend” is the clue that the definition is not correct  for FRAs. FRAs are interest-rate  or currency agreements, not stock agreements,  which means dividends are not involved.

A more general yet accurate definition is, “The calendar used to adjust payments dates when payments fall on holidays.” Although that is not specific to Canright Communications systems or FRAs, ii is accurate and won’t call attention to itself.

If in doubt, use a safe definition and mark it with Draft conditional text so a reviewer will know to look at it more carefully. The closer an external source is to the capital markets, trading, and securities the better.

See Resources>Glossary References page for common sources of definitions.

Write lists using conventions for these two list types:

1. Definite
2. Indefinite

Definite Lists

Precede definite lists with a lead-in sentence that states how many items are to follow. Number the items themselves.

Example:

Perform the following three tasks in the order in which they appear:

1. Start
2. Run
3. Exit

Indefinite Lists

Precede indefinite lists by a lead-in sentence ending with a colon. Bullet the items themselves.

Example:

The New View functionality is used most commonly in the following fields:

• Instrument
• Security
• Symbol

Important information about the task displays on each task tile for quick reference, including:

• The role associated with the task (Group Owner, Manager, )
• Names and usernames for whom the task covers
• The group for which the task is associated
• The name and username of the person making the request
• Delegate information for delegated tasks

For longer lists, use a bold lead in, followed by an em dash. Use a period after complete sentences.

Example:

Based on your entitlements, you may have access to any or all of the following search options, which enable you to display search criteria for the selected type of search:

• Transactions-Searches for transaction details.
• Account Positions-Searches for account position information (useful in attributing lolling on P&Ls).
• Desk Positions-Searches for desk position
• Saved Queries-Provides access to any saved queries and to the functionality used to save queries

Following are situations that have either caused confusion or required examples for the sake of consistency. Feel free to add others as required.

e.g. vs i.e.	These abbreviations are short for the Latin phrases exempli gralia, which means “for example,” and id est, which means “that is.” When using these abbreviations, follow these simple rules: ·       If your example is a complete list, use i.e. and format as follows: (i.e., north, south, east, and west) ·       If your example is a partial list, use e.g. and format as follows: (e.g., 10, 20, 30, etc.)
Version	Use v followed by the version and release numbers when listing a software release, e.g. Pricing Tool v2.3.5
Formulas	Follow math rules, first parentheses, then brackets, then braces, always in pairs: { [ ( ) ] }