B
Y L E T T Y S M I T H
Lone Star Chapter
This article covers four topics:
- An introduction to the concepts and purpose behind Lotus Notes groupware software
- A review of some of the strengths and weaknesses of Lotus Notes as a documentation tool
- Guidelines as to when using Lotus Notes as a documentation tool would be more or less effective
- Four database ideas to try.
This article is based primarily on Lotus Notes Version 4.6, but the information is general enough to be useful regardless of the specific version implemented, including the new Lotus Notes 5.0 release.
Lotus Notes is a database-oriented groupware product. If you are unfamiliar with groupware, its primary feature is that it allows a group of users to interact when creating, modifying and sharing information. All information used in Lotus Notes is stored as part of a database. For example, a company that implemented Lotus Notes might create databases for:
- Sharing ideas for new products and development options
- Tracing the workflow of a software development project
- A discussion group on new trends in the business area
- The company calendar
- Employee e-mail
- Customer addresses
- Help desk incident tracking
- Project management information and scheduling
- Company bookkeeping
- Employee time tracking for billing.
Each database has a variety of security levels to give different groups of users different levels of access to the database.
Documentation created with Lotus Notes is usually delivered in one of two formats: as part of a Lotus Notes database, or via the Internet using a web browser as part of a documentation web site. This option requires the implementation of the Lotus Domino Application Server – a web platform and development tool.
The strengths of Lotus Notes as a groupware and database tool are the same strengths it has when creating documentation.
- Documentation can be organized and arranged in a variety of ways, either at the database level by the database designer, or by the user who can create private views to sort and arrange the information. Technical information in particular responds well to this type of organization.
- A group of people can collaborate in creating organized documentation databases.
- Lotus Notes uses a replication process to update databases. This process resolves conflict when copying data from one database to another, so the stability of the database is strong.
- With the replication process, data can be shared to other networks, for fast document delivery and remote access.
- Lotus Notes is available on a variety of platforms.
- With the use of forms, formatting can be structured and maintained in one place, rather than requiring changes throughout the database.
The group-oriented nature of Lotus Notes works particularly well in documentation. Lotus Notes can automatically create review cycles, routing documents from person to person as they are completed, edited and approved. Each person can contribute text, graphics, spreadsheets, or multimedia files as part of the document. This lets groups of technical writers work seamlessly on large documentation projects.
The biggest weakness of using Lotus Notes from the perspective of creating documentation is that Lotus Notes is not a word processor. There is a lack of text tools to create and maintain text. Some examples from Version 4.6:
- Lotus Notes has only one variety of bullet, a round one. There is no second-level bullet.
- There is no way to search and replace special characters, such as hard returns or style tags, in Rich Text Format fields.
- Style tags (in my opinion) are somewhat buggy and are not as easy to apply as in some other applications.
The lack of text tools can be overcome by creating text-processing tools that interface with a word processing program, exporting text formatting from the word processor into Lotus Notes and vice versa. Currently, however, there is no commercially available tool for making this conversion. Such tools have to be developed and maintained in-house, and require considerable expertise in Lotus Notes development.
A problem that some writers experience is a lack of documentation control. In most text-based applications, the writer of the document has complete control over format, form, and presentation. Because Lotus Notes is a database tool, text presentation is controlled at the database level. Controlling format, form and presentation frequently requires using forms and/or specialized views that select certain documents and create uniform document templates.
While this level of control is a strength in some respects, it can also be a weakness. For example, if you want to change a font or add a disclaimer, you have to change it only once on the form and the entire database reflects the change. Simple changes may require a familiarity with the Lotus Notes script language, forms and view creation techniques. This can require training for the technical writing staff, or separate implementation by a Lotus Notes developer. Technical writing staff may or may not be comfortable with the "programming-like" nature of controlling Lotus Notes databases.
Another problem is that hotspots and links are not as easily created and maintained in Lotus Notes as in other Winhelp or HTML-based tools, such as RoboHELP. Hotspots are created in a three-step process. This process usually requires closing the current document, selecting a second document, and then reopening the first document. In situations where a large number of links are needed, this could add substantial time to documentation tasks.
Does my audience have access to Lotus Notes? If not, do I have the support to make it available via the Internet?
Lotus Notes was initially designed for situations in which the creator and the user of the information both run Lotus Notes. This problem has been largely solved by the development of the Lotus Domino Application Server, which makes Lotus Notes databases available via a web browser. It is possible to provide the same database to Lotus Notes users and web browser users. If you choose to implement this solution, however, be aware that it may require additional support and expertise.
How committed is my organization to using Lotus Notes?
Lotus Notes is not just a software package, it is a way of doing business. If your organization spends a significant amount of time using Lotus Notes as part of its daily routine, then creating documentation in Notes makes sense. The technical writing staff will be comfortable using it as a tool, and the infrastructure to support and maintain your documentation will be in place. If this is your organization’s only use of Lotus Notes, however, it will present more difficulties to use.
How structured is the information I am going to present?
The greatest strength of Lotus Notes is its ability to organize data. The more structured the information you have to present, the greater likelihood that you can arrange and sort the documentation into useful structures for the end user. For example, you can use Lotus Notes to create a database of field names and values for a database product. You can arrange the information by database table, field name, field type, system, or process. Users can access the information by whatever arrangement makes sense to them. If the main body of documentation you are creating is general concepts, such as introductions and long discussions, then the information may not be as conducive to being organized in this way.
If you are considering or have implemented Lotus Notes, here are some ideas for creating documentation that you may not have considered:
- A feedback database where users can report inaccurate or incorrect documentation. You can track the problem as it is reported, analyzed and resolved. With some programming, you can see the page on which a user was when the user created the feedback.
- A database of databases. You can list all the documentation that is available. In many organizations, it is difficult to keep track of what everyone has already written. Keeping a list in one place can prevent duplicated efforts.
- A style guide, or "Best Practices"-type guide. We have our style guide on Lotus Notes, separated into documents with titles like "Punctuation and Grammar," and "Formatting Documents for <Project Name>." Anyone with a question can quickly see if there is a guideline for a given situation. If there isn’t, we discuss the situation via e-mail and determine a resolution. By putting the resolution into the style guide, it becomes a living document, responding to the needs of the technical writers on a timely basis. This is also a good place to keep boilerplate language, such as for warranties and disclaimers for all writers to use.
- Data-flow documentation. You can create one database that shows where Field A in Database B is transferred to Field X in Database Y, and back again. This can be sorted by field, field type, database, link, process or whatever useful type of data you choose to keep about the link or the process.
If you are interested in learning more about using Lotus Notes in documentation, check with the Lotus Notes web site, http://notes.net. You can also check the Lotus web site, http://www.lotus.com/, for a bountiful list of ideas, solutions and documentation on the Lotus Notes and Lotus Domino products.
- Lotus, Lotus Notes, and Domino are trademarks or registered trademarks of Lotus Development Corporation in the United States, or other countries, or both.
- Blue Sky, Blue Sky Software, and RoboHELP are trademarks or registered trademarks of Blue Sky Software Corporation in the United States, or other countries, or both.
Letty Smith (lsmith@ctilimited.com) is a technical writer in the Dallas area. She works for CTI Limited, Inc., a commercial real estate software firm, as a Lotus Notes documentation creator. She is a member of the STC Lone Star Chapter, and the moderator of the Lotus Notes Technical Communicator discussion list.
Volume 2, # 2