Making SGML Easier with Microdocument Databases   Table of contents   Indexes   Publishers wanted, authors needed! The new information age is waiting for your works
  Smith  Tracy 
 

Intuitive SGML: database integration in SGML authoring

 

Abstract:

 Authoring in SGML is difficult and time consuming. Creating SGML documents is costly and complex. Although many of the SGML authoring tools available provide superior SGML functionality, many are not intuitive. This paper will discuss Novell's approach to creating structured hypertext documents intuitively and efficiently by integrating and customizing current database and SGML authoring technologies. The main goal of the system Novell developed is to optimize the authors ability to create and manage structured content.
 The focus of the presentation will be a demo of the tool Novell developed to solve many of these problems.
 

Introduction

 There are many problems facing companies today that create large volumes of information. SGML has become the solution to many of these problems. But even with the benefits that SGML provides many problems still exist. SGML, while solving some problems, causes others.
 There are five main problems Novell had to overcome in creating and maintaining its documentation. These problems are:
 
  1. Information Management
  2. Link Management
  3. Indexing
  4. Consistency/Structure
  5. Usability of Authoring Tool
 

Information Management

 Trying to manage information in high volume projects is often frustratingly time consuming. Even without the added complexity of SGML, large projects are difficult to manage. Especially with multiple writers who work in different locations. Examples of information that Novell wanted to manage include:
 
  1. Graphics
  2. Information objects (topics)
  3. Information owners (author)
  4. Information status (1st draft, 2nd draft, ...)
  5. Information IDs
  6. Information location
 Much of this information is stored in a database to allow for immediate access and to facilitate collaborative authoring. Information is organized in small re-usable chunks that we call topics. A project can consist of thousands of topics that are centrally located. This system minimized the overhead of managing, organizing, finding, assessing, and re-using the information.
 

Link Management

 In large, link intensive projects, the time spent managing links can exceed the time spent creating the content. Examples of link issues Novell had to manage and overcome include:
 
  1. Location of links
  2. Unique identification of links
  3. Coordinating linking among collaborating authors
  4. Link integrity due to additions, deletions, and modifications of links.
  5. Effects of broken links.
 Novell's solution is to organize linking into categories. For example:
 
  1. Imbedded links
  2. Links that display the title of what they reference
  3. See Also links
  4. Previous/Next links
  5. Links based on topic relationships
 These categories are also managed in a database. For example, if a topic within a project gets deleted; some link categories may allow for automatic deletion of references to that topic.
 

Indexing

 Traditional indexing is very time consuming. When doing collaborative authoring, it is difficult to maintain consistency within an index. To correct consistency problems, there is generally a lengthy index generation process. If corrections are made in the generated index that affect the source, it is necessary to find all the sources of that index term and make the corrections. In addition, an index must usually be started from scratch for each new project. This problem is so overwhelming that some documentation groups don't produce an index.
 Novell's solution is to have the generated index always exist in the database. When an author wants to add a new index term, they can see the terms that already exist. This approach reduces problems of inconsistency and the need to reconcile terms created by multiple writers. With our system, adding an index term to a topic is as simple as point and click. While editing index terms, authors can see all topics that use that term. If a term is changed, the change is automatically applied to all topics using the term.
 In addition, because index terms exist in the database, indexes can be leveraged from one project to another.
 

Consistency/Structure

 All too often in non-structured authoring environments, it is difficult to enforce or maintain consistency, especially for projects requiring collaborative authoring. There is no way to automatically enforce company styles or standards without a high degree of training or monitoring. This inability to control consistency often means significant increases in localization and translation costs.
 One of the goals our system achieved was to incorporate a structured editor into a collaborative environment.
 

Usability of Authoring Tool

 Many structured authoring tools today are difficult to learn and non-intuitive. Even many structured authoring principles are counter-intuitive to natural writing styles, for example the concept of separating content from format is hard for some to grasp. Some tasks, such as indexing and table creation, are even more difficult to do in some structured editors.
 Most non-structure authoring products provide ease of use, but are usually limited to a single output. Novell's solution tries to match that ease of use, while providing the benefits of single source, structured authoring.
 

Conclusion

 Novell's solution takes the power of Oracle, the ease and intuitiveness of Delphi, and the familiarity of FrameMaker and weaves them into a structured system that significantly increases the productivity of authors. The first project that used this system indicated that we can reduce writing and production time by 20-30 percent in comparison to off-the shelf tools that focus on a single output, such as RoboHelp or ForeHelp. Novell's solution provides a way to get documentation to market faster and in any required output.
 

ACKNOWLEDGEMENTS

 This paper would be incomplete unless I acknowledged Alan Murray, Chad Scholes, Curtis Graham, and Rita Harrison. Thank you.
Making SGML Easier with Microdocument Databases   Table of contents   Indexes   Publishers wanted, authors needed! The new information age is waiting for your works