Developing Online Help in Lotus Notes Workshop

Lotus Notes help system development at Deloitte & Touche is a joint effort between Lotus Notes developers, content experts, graphic artists, and technical writers. The guidelines below explain how a help system is designed, the basic help system structure, and procedures for creating help topics.

Each help system is developed using a form. The D&T form contains a predefined heading section, a section for the help system text, and hidden fields that are used to control the hierarchy of topics within the help system.

Workshop Objectives

    • Create effective Lotus Notes help systems
    • Plan a numbering system for help topic levels
    • Design a help form
    • Create and edit help topics
    • Use links, hotspots, and collapsible sections
    • Attach supporting documents
    • Create or capture graphics for use in a Notes help system
    • Create a view
    • Create effective navigation (graphical vs. text)
    • Make the help system context sensitive (pros & cons)

 

Lotus Notes Terminology

Category—used to organize documents in a view. To make categories available in a view, the database designer must set a column to sort on a "category" field from a document.

Document—individual pages that store the data for a database. The type of information that can be entered in a document depends on the type of fields it contains.

Field—a form design element that can contain various types of data including static text, numbers, rich text (text, graphics, links, pop-ups, collapsible sections, and attachments), and drop-down lists (keywords).

Folder—used to store and manage related documents without putting them in a category.

Form—a framework for entering documents in a database. It can also be used to control how you edit, display, and print a document. A form can contain fields, static text, graphics, and special objects (links, attachments, collapsible sections). A form translates into the viewable screen once they have been completed.

Hotspot—text or picture in a rich-text field that can be clicked to perform an action (jump, pop-up, etc.)

Link—a jump that gives you direct access from one Notes document, view, or database (source) to another document, view, or database (target). Notes opens the target object without closing the source object.

Pane—the navigation pane defaults to show folders and views. This pane can contain a graphical navigator. The view pane contains a list of the documents available in the database.

View—contains a list of documents in a Notes database. In a view, you can search for specific text, select and open documents, copy and paste documents, and print the documents or the view.

View Pane—contains rows and columns. There will be one row for each category or document title and one column for each type of information displayed.

Demonstration

In this demonstration, we will show you several versions of Notes help systems.
    • With various navigators
    • One generic navigator
    • Graphic navigator—SOS Help System

Effective Help System Tips

Good help system development principles apply to Notes help systems, too.
    • Know your audience: Always analyze your audience before you begin a help system project. You need to know your user’s level of expertise to create an effective help system.
    • Understand the project scope: You need to know what you are creating as much as who it is for. Is this a reference or perhaps a tutorial? Will you need to use more than one type of topic (task, context, reference, definition, demo, navigation)? If so, which ones will you use?
    • Prepare a topic outline: You can’t begin authoring your help system before you determine what you want in it and the order in which you will present the information.
    • Plan your navigation scheme: How will your users find the information they are looking for? Where will you use jumps? Do you want to use pop-up definitions? If so, determine when to use them so you can do so consistently. Determine if there is additional information that can be included from other source materials (attachments).

Workshop Scenario

Our scenario for the workshop exercises is based on the Zany Zoo Animal Adoption Agency. This agency was founded in 1975 by Frank and Jessica Dolittle. It is located in Phoenix, Arizona.

Frank and Jessica have devoted their lives to the study of animal behavior in captivity. Because of their love of all wildlife, they started the Zany Zoo to care for unwanted or injured animals throughout the United States.

The Dolittles have created a Notes database to track all the animals at the Zany Zoo, their feeding needs and habits, their preferred habitats, and the people who have adopted their animals. In addition, this database is used as a marketing tool for potential adopting families. They have asked us to create a help system for the general public who will be accessing their database to get information about the Zany Zoo, the animals that are available for adoption, the Zany Zoo adoption policy and form.

Some of the animals currently at the Zany Zoo include:
    • Ollie, a five-year old Ostrich. Ollie was abandoned on a farm in New Mexico, and was suffering from wounds inflicted by a Coyote attack. He is in good health now, and is looking for a home. Ollie loves to eat oats, but he can easily fend for himself by eating insects. The preferred habitat of an Ostrich is dry flatlands and a moderate temperature. Ostriches do not take to cold climates, and they cannot be kept in small, confined areas. They really need wide-open spaces to run around in and explore.
    • Fiona, a two-year old Llama. She was the valued pet of a family in Northern California until she decided to be a "watchdog." Apparently Fiona has great protective instincts. However, her habit of charging and knocking down strangers was not acceptable behavior for the family’s nursery business. So, Fiona is looking for a home. She prefers a cooler, mountainous climate with plenty of space to roam.
    • Buddy, a ten-year old Collie. He is well trained as a working dog, and would be great for a small farm. Buddy is getting along in age, but he has a young spirit. He has already begun training some of our other dogs here at the Zany Zoo.
    • Elsa, a six-month old Rhodesian Ridgeback. She was brought to us because of her size. At this young age, she is already sixty pounds and growing. She will be approximately 110 pounds when she is full-grown. She is very friendly, and will make a great watchdog. Elsa needs a good bit of room to run. She is well behaved, and is learning lots of good habits from Buddy.

Our task in this workshop is to create a help system for the Dolittles’ database.

 

Plan a Numbering System for Help Topic Levels

The numbering system is used to maintain the content hierarchy in the Notes database. You should create a numerical hierarchy to correspond with each section, subsection, and document you create.

The best advice for creating a numbering scheme is to keep it simple and document it.

If you create a help system without a numbering system, all topics will be displayed alphabetically and you will have no control over the order. This could be successful for a glossary of terms where you want everything to display alphabetically, but for most help systems it is not practical.

Changing the numbering system after the database has been populated is possible, but time consuming.

EXERCISE 1: Planning the Numbering System

Before you can create your numbering system, you need to determine the structure and topic types you will use in your help system. If you do not have this structure clearly defined, you will not be able to create a numbering system to meet your needs.

So let’s take a few minutes to develop our structure and then we will determine the numbering system for the Zany Zoo database help system.

Basic Help System Structure

Use this section to identify your main topic titles and subtopic headings.

Main Topic 1:
    • Subtopic 1:
    • Subtopic 2:

 

Main Topic 2:
    • Subtopic 1:
    • Subtopic 2:

Main Topic 3:
    • Subtopic 1:
    • Subtopic 2:

Numbering System

Use this section to determine your numbering system (e.g., 1.0 Overview).

Section titles & numbers:

 

 

Topic headings & numbers:

 

 

Subtopic headings & numbers:

 

 

 

Design a Help Form

A form in Notes is used to control how you edit, display, and print a document. It is a template for creating the database documents. Since the form we will be creating is for the help system content, we will refer to it as a help form.

You need this form to create the look of your Notes help system. All content entered into a form is saved as a document in the database. When a help topic is clicked, the user sees the corresponding help document.

The help form should contain at least a title area, a content area, and an area for hidden fields. These are known as elements in Notes. Additional elements include labels and fields.

The title area is where you will enter the title of your help topic. The content area is where you will enter the topic information. This area should be a rich-text field so that you have optimal flexibility in the design of your content. By using a rich-text field, you can create jumps, links, hotspots, collapsible sections, and include attachments in your content. The hidden fields are where you will control the help section the content is displayed in, the name of the section, and the order in which the help topic is displayed. A hidden field can also be designed to display an audit trail of changes to the document, the name of the author, etc.

 

EXERCISE 2: Designing and Creating a Help Form

To do anything in a Lotus Notes database, you must have a Notes ID and at least author rights to the database you will be working in. Also, if you will be developing forms or navigators, you will need a developer ID. Once you have the appropriate rights and your ID, you can create your help system.

Designing a Form

Let’s design the help form. In the space below, sketch the elements you think will be needed for this form.

 

Creating a Form

To create a form:
    1. Start Lotus Notes.
    2. Click the icon on your workstation for the database you want to open.
    3. From the Create menu, select Design, Form. You will see a blank form.
    4. From the Design menu, select Form Properties.
    5. Click the Basics tab and type a name for the form in the Form Name field.
    6. Click the Background tab and select a background color from the Background Color list box.
    7. Create a title for the form by typing the text onto form. You can then select the font, size, and alignment for the title.
    8. Create labels for the fields you want to include on your form by typing the text for the labels. You can also select the font, size, and position for the label.
    9. Place the cursor in the space after a label and select Create, Field to create a field that corresponds to the label.
    10. Next, double-click the field, name it, and make it an editable text field. If standards don’t already exist for naming fields, you should work with a developer to create them.
    11. Save and close form.

Demonstration

Now that you have designed the form on paper, we will demonstrate how the form is created in Notes.

 

Create & Edit Help Topics

Creating New Help Topics

To create a new help topic:
    1. Start Lotus Notes.
    2. Click the icon on your workspace for the database you want to open.
    3. From the Create menu, select the help form. You will see a blank help form.
    4. Enter the topic title in the first blank field.
    5. Enter the body text (content) for this topic.
    6. Enter the appropriate hidden field text and numbers.
    7. From the File menu, select Close.
    8. Click Yes to save your changes.

Editing Existing Help Topics

You can easily make changes to the help topics you create. To change an existing help topic:
    1. Start Lotus Notes.
    2. Click the icon on your workspace for the database you want to open.
    3. Access the help system.
    4. Click the section title on the help navigator.
    5. Double-click the topic you want to change.
    6. Right-click anywhere on the screen and click Edit.
    7. Make the necessary changes and select Close from the File menu when you are finished.
    8. Click Yes to save the changes and return to the help navigator.

 

EXERCISE 3: Creating and Editing a Help Topic

Now that we have designed and created a help form, we can begin entering the help content. To enter this content, you will create a help document for each topic. As you enter content, you can style the text to meet your needs. Notes also enables you to create styles that you can apply across documents, run a spell check, and change the font size, alignment, and color. Whenever you are styling text, it is a good idea to create standards so that your documents will be consistent.

Let’s create a help topic to contain general information about the Ostrich.

 

Links, Hotspots, & Collapsible Sections

While creating the content for your help system, you can use several features available in Notes to navigate easily through your help system. These features are only available in a rich-text field, so you will want to make sure that the body area of your help topics are created as rich-text fields.
    • Link: In Notes, a link is a jump that gives you direct access from one document, view, or database (source) to another (target). Notes opens the target object without closing the source object, so you can easily return to it.
    • Hotspot: A hotspot can be either text or a graphic. It can only be created in a rich-text field. You can use a hotspot to jump to another place in the database, to jump to a website, or to pop up supplemental information.
    • Collapsible Section: You can use sections to collapse one or more paragraphs in a document into a single line. Sections make navigation in large documents easier. Readers can expand a section when they want to read its contents. Sections are useful for organizing documents that contain a lot of information. You can group related information in a large document into different sections.

Creating a Link

You can create a link to switch to another document, view, folder, or database.

Note: You must be in a rich-text field to create a link.

You may want to create links between your help topics. To create a link:
    1. Open Lotus Notes.
    2. Click the icon on your workspace for the database you want to open.
    3. Access the help system.
    4. Click a section title on the help navigator.
    5. Double-click the help topic you want to link to.
    6. From the Edit menu, select Copy As Link, Document Link. You could also create a view, folder, or database link by doing one of the following:
    • To create a link to a view or folder, select or switch to the view or folder and choose Edit, Copy as Link, View Link.
    • To create a link to a database, select or open the database and choose Edit, Copy as Link, Database Link.
    1. Return to the help navigator.
    2. Double-click the document you want to place the link in.
    3. Right-click and select Edit.
    4. Select the text you want the user to click to access the link.
    5. From the Create menu, select Hotspot, Link Hotspot. A green box displays around the text that the user will click to jump to the linked text.

Creating a Hotspot

You can add a hotspot to an area of a document (such as text or a graphic). You can use hotspots to:
    • Create a pop-up
    • Create a link
    • Create an action
    • Create a URL link to a page on the Web

Note: You must be in a rich-text field to create a hotspot.

For example, you may want to create pop-up definitions in your help system. To create a hotspot:
    1. Open Lotus Notes.
    2. Click the icon on your workspace for the database you want to open.
    3. Access the help system.
    4. Open the help topic you want to create the pop-up help in.
    5. Select the text you want to attach the pop-up help to.
    6. From the Edit menu, select Create, Hotspot, Text Pop-up.
    7. Enter the text for the pop-up in the dialog box. You can either choose to have a border around the text or format the text according to your standards.
    8. Close the dialog box to activate the pop-up.

Note: You must be in read mode to display pop-up text. To test a pop-up hotspot after you create it, return the document to read mode.

Creating a Collapsible Section

You can collapse one or more paragraphs into a section that can be expanded when you want to read its contents.

Note: You must be in a rich-text field to create a collapsed section.
    1. Make sure the document is in edit mode.
    2. Select the paragraph(s) you want to collapse into a section.
    3. Choose Create, Section.

Tip: Notes uses the first paragraph as the section title by default. To change a section's title, use Section, Section Properties.

 

EXERCISE 4: Creating a Link, a Hotspot, and a Collapsible Section

In the help topic we just finished for the Ostrich, let’s add a Related Topics section to include information about their preferred habitat and the Zany Zoo adoption procedures. We will need to create these help topics and then add them as links under the Related Topics title on the help document. Once we have done that, we will make the Related Topics section into a collapsible section.

For our Hotspot, we will be creating a pop-up box to contain additional information on the Rhodesian Ridgeback breed.

 

Attach Supporting Documents

You may want to attach files to your help topics. You can attach virtually any type of file to a Notes database, including binary files, compressed files, executable files, word processing files, spreadsheet files, etc.

When you attach a file, you're actually attaching a copy of the file, so the original is not affected. If you have the application installed, Notes displays an icon indicating the file type and name. If not, Notes displays a generic icon.

To attach a file:
    1. Open Lotus Notes.
    2. Click the icon on your workspace for the database you want to open.
    3. Access the help system.
    4. Navigate to the help topic you want to access and double-click it.
    5. Right-click and select Edit.
    6. Place your cursor in the help topic on the location for the attachment.
    7. From the File menu, select Attach. The Create Attachment(s) dialog box displays.
    8. Select the drive and directory that contains the file you want to attach.
    9. Select the file you want to attach to the help topic.
    10. Click the Create button. The file is attached and you will see an icon with the filename below it.

DEMONSTRATION: Attaching a Document

In this demonstration we will attach an adoption form to the help topic for the Ostrich. We will also show you how an attached document can be viewed using the Notes Viewer or opened (launched) in its native application.

 

Create or Capture Graphics for a Notes Help System

There are many uses for graphics in a Notes help system. You may decide to have a graphic navigator for your help system or you may want to include graphic elements that will enable your user to better grasp an idea, understand an icon, or recognize a navigation button.

When including a graphic navigator there are size, palette, and file format considerations you should keep in mind:
    • Main navigator—make sure the graphic is approximately 456x780 for a display set to 800x600. This allows the user to view the main navigator without having the toolbar and message areas of Notes interfere with the design of the navigator. Note: This size may vary a little.
    • Subnavigator—the graphics should be 120x439. This leaves you with ample viewing space for the document titles. Note: This size may vary a little.
    • Color—for the best results, use the Notes palette. You can also use the web 216 palette if you are developing in notes 4.6. Using either of these palettes will ensure that every user sees the colors you intended them to see, and puts an end to annoying palette flashes.
    • Icons—the size should be 32x32 pixels, and use no more than 16 colors.
    • File format—the best file format is a bitmap. You should create all graphics as 8 bit, and use only 256 colors. In Notes 4.6 you can use a GIF or JPEG file, but you must force it to the Notes palette.

Note: When graphics are finalized, you can achieve the smallest file size possible by forcing to an exact palette in PhotoShop or by using Debabilizer by Equilibrium to achieve the same results.

DEMONSTRATION: Adding Graphics to the Help System

In this demonstration, we will show you how to insert a picture of an Ostrich in the space available on the help document.

 

Create a View

A view is used to display the documents contained in a Notes database. When you create a view, you need to determine which documents to display and the order in which to display them. You can also set the size of the columns that will contain the document titles.

Once you create a view, you can also create an action button to access that view. This is especially useful for a help system because the button is prominent on the screen so the user can access it easily.

To build the view:
    1. Create a new Shared View in the database.
    2. Create a hidden column for each section, subsection, and document title (document number field) to establish the sort order.
    3. Following each hidden column, insert the corresponding column for the section, subsection, and document title to be displayed in the view, formatting it as necessary.
    4. Choose File, Close and save your changes.

DEMONSTRATION: Creating the Help View and Adding a Help Button to the Notes Action Bar

In this demonstration, we will show you how to create a help view based on the topics we have created throughout the previous exercises. We will also cover how to access that view by adding a button to your Notes action bar.

 

Create Effective Navigation

Once you create your documents and the view to display them in, you will want to create your navigation system. You can create a text or graphic navigation system in Notes.

In a help database, you will probably want the navigator to show your table of contents. You can create this navigation system with one navigator or multiple navigators.

Using one navigator means that you will have lower maintenance when you make changes to the help system. However, using one navigator will limit your ability to create context-sensitive help.

Using multiple navigators will give you more flexibility in establishing context-sensitive help. Additionally, you can use multiple navigators with graphics to apply a more graphically pleasing interface to your help system. However, multiple navigators mean more maintenance time when making changes to the help system. The time involved grows logarithmically as new help sections are added.

DEMONSTRATION: Creating a Navigation System

In this demonstration, we will show you how to create a simple text navigation system. This type of system is easy to create and maintain.

We will also show you how to make a graphic navigator functional.

 

Make the Help System Context Sensitive

Many Notes applications can benefit from having context-sensitive help systems. Notes gives you the ability to create links to databases, views, and documents.

Making the help system context sensitive enables you to open help to the information the user will need while in a particular section of the Notes application.

DEMONSTRATION: Creating Links and Views to Make a Help System Context Sensitive

Now, we will demonstrate how to create the necessary views and links to those views to create an effective context-sensitive Notes help system.

 

A Look at Advanced Applications of Help Systems in Notes

We will now take a look at other alternatives for help systems in Lotus Notes:
    • Launching a WinHelp file
    • Viewing a Notes help system through a Web browser

Launching a WinHelp File in a Notes Database

During this demonstration, we will discuss:
    • How to attach a WinHelp file to a Notes database
    • Using LotusScript to deploy and launch the WinHelp system.

Viewing a Notes Help System through a Web Browser

During this demonstration, we will discuss:
    • Reasons why you would want to view Lotus Notes databases through a browser
    • What Domino is
    • How Domino is different from Lotus Notes

Sample Deloitte & Touche Help System Information

The following pages contain information specific to the development of existing Notes help systems at Deloitte & Touche. It includes explanations of the hidden fields we use and a copy of our standards for formatting Notes help systems.

The D&T Help Form

The D&T help form contains three fields:
    • Topic Name—for the title of the help topic. This text will display in the help system exactly as you enter it.
    • Body—for the content of the help topic. Refer to the Help System Standards section for information on fonts, colors, and text size. These standards will enable you to keep the look of your help topics consistent.
    • Hidden fields—these fields display only in Edit mode. They are used to control the document hierarchy in the help system. Refer to the Hidden Fields section below for more information on why hidden fields are used.

Hidden Fields

This section contains examples of hidden fields used in D&T Notes help systems and how they are used.

What views does this document appear in?

This hidden field should contain the name of the view that the help topic will display in. This is a keyword field that you can build as you develop your help system. For simplicity, keep this keyword short.

Example:

Keyword: Know

In our Knowledge Network help system, this keyword is the name of the main view for this help system.

What top-level category does this document appear in?

This hidden field should contain the title of a section in the view that the help topic will display under. This is a keyword field that you can build as you develop your help system. This keyword must be the exact name that you want to display in the help system. Its number determines the order in which the section is displayed.

Example:

View Name (Keyword): Know

Category: 1.0 Knowledge Network

What subcategory does this document appear in?

This hidden field should contain the name of the applications view that the help topic will display under. This is a keyword field that you can build as you develop your help system.

This keyword must be the exact name that you want to display in the help system. Its number determines the order in which the subcategory is displayed.

Example:

View Name (Keyword): Know

Category: 1.0 Knowledge Network

Subcategory: 1.3 How Do I. . .

What number is the document?

This field should contain the number of the help topic. Be sure to number topics using multiples of five. This enables you to add topics later without having to renumber all of the existing topics. This number determines the order in which the topic is displayed within a subcategory.

Example:

View Name (Keyword): Know

Category: 1.0 Knowledge Network

Subcategory: 1.3 How Do I. . .

Document Number: 1.305

D& T Help Topic Types & Structure

D&T help systems typically consist of four types of help topics. These topic types are displayed in the following order:
    • General Information—for introductory or overview topics.
    • Navigation—for defining buttons, symbols, and other navigational topics.
    • How Do I. . .—for procedural topics.
    • FAQs—for reference topics: who to contact, when to do something, roles and responsibilities, etc.

D&T Help System Standards

The following style standards were developed for D&T Notes help systems. Using standards will ensure that the look of your help topics is consistent.

Body text
  • 10pt Arial
  • Left Indent: 1"
  • Spacing Above: 1.5
  • Spacing Below: Single

Numbered text
  • 10pt Arial
  • Spacing Above: 1.5
  • Spacing Below: Single
  • Left Indent: 1.4
  • Apply numbers in Notes, not in Word

Bullet
  • 9pt Arial
  • Spacing Above: 1.5
  • Spacing Below: Single
  • Left indent: 1.4"
  • Apply bullets in Notes, not in Word

Notes
  • The word "NOTE" should be all upper-case
  • Bold the word "NOTE", including the colon
  • Change the color to red
  • Use one space after the colon

"To" statements
  • Make the entire statement, including the colon Bold and Dark Magenta
  • Enter one line space after the "To" statement

Pop-up text
  • 10pt Arial
  • Blue text, plain, underlined

Jump text
  • 10pt Arial
  • Green box
  • Bold

Headings within text
  • 10pt Arial
  • Bold
  • Spacing Below: Double

Button Naming and Position
  • The button calling the Knowledge Network help main contents screen should be called "Help," not "Help Topics" or "Help Contents." It should also be placed at the far-right end of the action bar.

Document Titles
  • Titles of documents (such as Path Guide and Summary Guide) should be bold.

 

Global Help System with Text Navigator

Pros: This type of navigator is the easiest to support. When views are added or removed, the developer adds or removes a text box and its links.

Cons: This navigator always opens to the same view regardless of where in the application the user enters the help system. This forces the user to click again to find the specific information needed.

The Local Applications section jumps the user to a view containing information from other countries. This section of the help system uses a different help form that enables the authors to specify their country when they create a help topic. The country specification tells Notes where to place the topic in the Local Applications area.

US Only Help System with Graphic Navigator

Pros:

  • Enables the designer to present a familiar help interface to the end-user.
  • Enables the developer to create screen-specific help jumps by linking each navigator to a view.
  • Gives the appearance of animation.

Cons: This is a maintenance nightmare. There are two graphics (open book and closed book) that must be maintained for each help section. For this simple help system, there are 14 navigators to show which section you are in.

 

US Only Help System with a Static Graphic Navigator

Pros: When a section contains only one topic, the topic is opened immediately when the user clicks the navigator. If there are several topics in a section, the user clicks the appropriate topic displayed in the view pane.

Cons:

  • Phrasing topics as questions causes the navigator to take up more screen real estate.
  • This navigator is a solid graphic with text hotspots. When a new topic is needed, the entire graphic must be replaced and the text hotspots must be rearranged.