Using documentation topics

Topics (DCC_Topic) are used for any kind of definition or description. Topics are not only used in Terminus, but are referred to wherever textual definitions are required. Thus, topics might be linked to any development resource (implementation class function, parameter, window, control etc.).

A topic may be linked with any number of resources, i.e. the same definition or documentation topic might be used for documenting different kind of resources. E.g. the content definition for a GUI field may refer to the property documentation topic created for the data source (property) of the field.

In order to provide structured documents, topics may be arranged in topic hierarchies (themes). Also in a topic hierarchy, topics may be referred to from different locations within the hierarchy. Topic hierarchies are defined via HirarchyTopics, which refer to topics to be placed into the hierarchy.

The details of the topic definition are displayed in the work area of Terminus. It contains a short title and a characteristic. One may also add examples, notes or other remarks. In order to refer to documents describing the topic more detailed, a document reference might be added to the topic.

When a topic is linked to one or more development resources, those resources are listed in the Resources list shown in the right panel. In order to associate concepts with the topic definition, those have to be added to the Descriptors list. References to other topic definitions can be defined in the References list shown in the right panel.

More complex topics may contain subtopics, which are integrated part of the topic definition. Subtopics are owned by the topic definition and will be deleted automatically, when deleting the topic definition.

The structure of subtopics is similar to the structure of the documentation topic. Subtopics also contain title and characteristic, subtopics, document references as well as links to other documentation topics or concepts. Links to other subtopics, however, cannot be created.

Subtopics may, again, have subtopics and thus, form a hierarchy. It is, however, suggested not using more than two subtopic levels (in most cases, one subtopic level should be sufficient).

In contrast to topic definitions, subtopics are not reusable and cannot be referred to by more than one topic. Subtopics cannot be linked directly to hierarchy topics or development elements and cannot be referenced by other topics.

When a subtopic shell be referenced in another context, it has to be turned into a topic definition, e.g. by selecting Move Left from the context menu in the themes tree or by copying the subtopic to the topic level in the topic list (Topics view).

Terminus supports several languages, which might be selected from a language selection box. This allows entering text in different languages, which is required in case of providing multilingual applications.

All topics and concept definition text blocks provide the language selection box, which selects the language for all text parts in the topic (characteristic, example, notes and others). Links to other topics or concept relations (generalisation, descriptors, references) are not language dependent but might be displayed with language specific texts.

When working with multilingual documentation, the developer is responsible for updating additional languages in case of changes in the documentation. There is automatic indication, that other language versions have to be updated.

Usually, the default language is selected automatically, when creating a new topic or concept. The default setting might be changed in the options dialog, which can be opened via the application menu Options/Setting.

For new applications, the language might be set also in the configuration or ini-file in Options.Documentation.DocumentationLanguage.

Changing the language settings for an existing database may result in empty forms, which will be provided for the new language.

When generating documents or WEB-sites from the Terminus database content, the language has to be set to the language for which the documents are to be created before starting the document generation. When generating documents from OSI or OShell scripts, the proper language has to be set in the script or system environment by setting the full option path as described above.

Documentation topics are, usually identified by a system number (__AUTOIDENT), which will be created automatically, when creating a new topic. In order to identify topics, numbers are often not very helpful. Thus, topics may get names, which might be entered in the Name field right panel (top). Names entered need not to be unique as long as names are only used as sort of short title.

In order to identify (associate) documentation topics via names, unique names have to be assigned and the documentation topic has to be "upgraded" to a named topic by pressing the button right of the Name field. After the topic became a named topic, the button will be disabled (grayed).

Only documentation topics upgraded to named topics can be associated e.g. as referenced topics or as documentation topic in a topic hierarchy.