Manual Structure

The purpose of Canright Communications user manuals is to give an overview of a software application and its intended use and audience. Manuals also provide an overview of the app’s functions, explain the business rules underlying the software where appropriate, and present the user­ interface that enables user to navigate the software. Manuals also give step-by-step instructions on functions while noting usage lips and potential problems where possible.

Manuals are not designed to train user’s on the business subject an app supports. An application manual explains how the application works, provides usage scenarios, and defines fields and commands. It does not attempt to teach a user the business concepts that the application supports.

Similarly, technical manuals are designed to provide an overview of core and application services to developers and other technically inclined readers. Each manual provides an overview of the system, including high-level logical and system architecture diagrams and definitions where appropriate. Manuals also include required system configuration overviews, maintenance and operations material, and troubleshooting tips.

Canright Communications manuals are designed to be generic and work for all clients while including examples to illustrate specific business uses. When software is developed for specific clients, we include any require client-specific documentation in a supplement to the main manual.

The following sections described the major content sections Canright Communications user and technical manuals.

We developed standard sections of user manuals to bring consistency to the entire Canright Communications application documentation  set. Given that the application itself determines much of the content, however, overall chapter structure tends to vary by manual.

Overview

This chapter provides a high-level description of an application, including its purpose, goals, and benefits.

What [Application] Does. This section may include the application’s functions, features, or similar information.

How [Application] Works. This section gives a high-level explanation of how an application accomplishes its functions. This may be a short explanation of other systems an application connects to, a description of underlying technology a user may need to understand, or illustration of the business process the application supports.

[Application] Concepts and Terminology. This section explains any critical concepts and defines any relevant terms.

How the [Application] User Interface Works

This chapter varies by application in terms of length and structure. Initially, these chapters documented the primary screen and its functions, followed by a chart explaining the main controls, etc. IN the Security Management Console II manual, this chapter goes into detail about each items on the web.

Function Chapters

Subsequent chapters depend on the application and its functions. For some applications, these chapters are reference oriented and detail major screens or functions. For the more complex applications, these chapters can focus on primary workflows, use cases, or other functional topics.

Entitlements

This chapter consists of a table that lists and defines the entitlements required for access to the application and its functions.

Appendices

Standard appendices include Symbol Search () and other sections

According to the original charter for Technical Communications, technical manuals are to cover installation, care and feeding, and troubleshooting. The following is the structure used for technical manuals.

Overview

The Overview section in a technical manual includes two diagrams, a high-level Logical Diagram and a more detailed System Diagram. There are two main questions when creating these diagrams for any service or system:

1. What feeds it?
2. What does it feed?

Canright Communications services and systems are designed to store and retrieve data and move it to and from other services quickly and in massive quantities. Systems are fed data by other internal and external systems and feed other systems, in turn.

Installation

The Installation chapter provides instructions for installing and configuring a service. This chapter discusses the prerequisites and requirements that must be met before installing a service, the variable values specific to your network, server, and client-systems, login and security for the

service, and database installation and configuration procedures. In some manuals, configuration is a separate section. In most, however, configuration procedures are included after installation and set up procedures in the Installation chapter.

Maintenance

The Maintenance chapter discusses monitoring and maintenance of the service. It details the operational procedures required for maintenance of a service in order for it to run properly and serve the business effectively.

Troubleshooting

The Troubleshooting chapter lists common problems that occur with the service and their possible remedies. Most troubleshooting starts with a review of the log files that the service(s) maintains.

Entitlements

The Entitlements chapter lists all of the entitlements required to operate the service/applications.

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.

Lists

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.

Examples:

• 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 sentnces.

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

Usage Notes and Examples

Following are situations that have either caused confusion or require 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: { [ ( ) ] }