1.1 Anatomy of a Technical Document

In its most basic instance configuration, a Technical Document-enabled Item is a single entity that contains formatted text, stored as XML in a single Property, and one or more associated graphics. Each of these Items references a Document Type that specifies the XML Schema, CSS Styling, and any configured content renderers/generators for automating the creation of XML content.

Tech-Doc Enabled Items can also reference other Tech-Doc Enabled Items and Business Objects creating a rich Digital Thread. The following sub-sections will provide a brief overview of each of the main features of the Technical Documentation Framework with links to associated sections for more information.

This document will refer to an ItemType, or an instance thereof, as being Tech Doc Enabled if this ItemType that has been configured to use the Technical Document Editor and store the XML Content in a configured Property. This document will also refer to Items of this type as simply a ‘Technical Document’. For the Technical Documentation Application, the tp_Block ItemType is an instance of a Tech-Doc Enabled Item.

Technical Documents have content maintained as XML, based on an XML Schema provided by the user. As authors add text and graphics to a document, XML Elements are generated and added by the system and stored in a single Property. The XML provides additional metadata about each Document Element and the XML Schema ensures that the structure of the document is consistent and compliant.

Figure 1 Sample Document - Showing Editor View

Figure 2 Sample Document - Showing XML Content View

In XML vernacular, the term ‘Element’ refers to the markup tag (e.g., <ElementName>) and everything that is included – as child Elements. This document uses the term ‘Document Element’ to identify the types of content that can be added to a Technical Document. Document Elements are stored as individual XML Elements with a name and optional Attributes, which provide additional metadata to be used to further characterize the Document Element, distinguish its style, etc. Document Elements derive from one of the following Types:

• Container – Use to contain other Document Elements – e.g., Chapter, Section.
• Formatted Text – Text that can have basic formatting applied by the author – bold, italic, underline.
• Unformatted Text – Text without author-specified formatting
• List – Container for List Item Document Types
• List Item – Container for content to be displayed in a List.
• Image – References a 2D graphic stored by a tp_Image ItemType.
• Table – Container for Row Document Types
• Row – Container for Cell Document Types
• Cell – Container for content to be displayed in a cell of a Table.
• Item – Container Element that can be associated directly with an Item.
• Item Property – Unformatted Text Document Element that references a specific Property on an Item referenced by a parent (or ancestor) Item Document Element.

The authoring process is guided by XML Schema Validation. The Document Elements that can be added at any place in the document is dictated entirely by the XML Schema contained in the associated Document Type and enforced by the Schema Validator. XML Schemas specify the XML Elements, Attributes associated with each, the hierarchy of these elements, and the cardinality. Note that not all the XML Schema schema is supported.

In addition to manual addition and removal of Document Elements, a configuration mechanism can be used to execute Content Generators – Method code – to automate the creation/update of Document Elements. This method is typically used when there has been association/reference set between a Document Element and a selected Item Instance whereby Property values from these referenced Items are used specifically to create text or graphics content in the document.

Technical Documents can have explicit relationships created with other Items maintained in Innovator. These Items are referred as ‘Business Objects’. This relationship establishes a direct binding between a Document Element and the associated Business Object, although the relationship is maintained by a RelationshipType between the Technical Document and the Business Object. In addition, property data from these Business Objects can be queried and used within the Technical Document. When the Business Object property data is updated, the associated Technical Documents are updated accordingly. This binding helps maintain data integrity and identify a link between Objects and the documentation that was created specifically for them.

Item Reference Configuration provides a mechanism to automate the creation of values for Properties of Referenced Items and validate content added by the author. Configured JavaScript Methods are used to apply custom business logic and set and/or verify Property Data.

When an Item Document Element is created in the Technical Document Editor, the author has the choice of choosing an existing Item to reference or create one at that moment. If an Item is created, the Item Reference Configuration (if defined) is used to prepopulate and/or validate Properties of the generated Item.

ItemTypes that can be referenced by a Technical Document must be configured as a PolySource for the tp_Item ItemType.

Document Elements can be configured as a ‘Mapped Property’. These Item Property Document Elements are associated with Properties based on the Property Name. The Item used specifically for Property content is determined by a Document Reference of some Document Element parent (or grandparent, etc.).

Using the following illustration as an example, assume that there exists an ItemType – Shipping Info – that contains the following Properties:

• Name: part_name, Label: Part Name
• Name: container_size, Label: Container Size
• Name: ship_weight, Label: Ship Weight

In addition, there exists a Technical Document with schema elements:

• ‘ShippingInformation’: Document Element of type ‘Item’ that references a ShippingInformation ItemType and a container for ‘LineItem’s
• ‘LineItem’: Document Element of type ‘Container’ that is a container for one Text Document Element – used for a Label – and one Item Property Document Element – used to reference an Item Property.
• Name: ‘ShipProperty’: Item Property Document Element

In the scenario above, the top-level Item Document Element references a specific Shipping Info Item with the Properties and values shown. Switching this top-level Document Element to reference the other Shipping Info Item would cause the ShipProperty Document Elements to update automatically to the values of this Item.

Filters provide a mechanism to ‘tag’ individual Document Elements with metadata (‘Filters’), which can then be used to hide content when published. Filters consist of a name and one or more values. For example – a document describing technical information related to an automobile may have a ‘Model’ Filter that can have values for each of models for a particular Make. “A4”, “A5”, “A6” are example Models for Audi. Filtered Document Elements provide a reuse mechanism to isolate (or hide) certain specific content and expose common content. Using the example, an author would be able to ‘publish’ a Technical Document filtered by a specific Model.

Technical Documents can exist either as a single entity - with all content contained within – or aggregate content from multiple document modules. Breaking up documents into smaller components has multiple advantages including the ability to:

1. Reuse each component.
2. Enable concurrent editing.
3. Apportion each component to areas of specific specialty or expertise.

In the Technical Publication domain, technical content is sometimes referred to as ‘Topics-based’ or ‘Modular’. This refers to content that is about a specific topic or area of focus and is, to some degree, context insensitive. This helps to characterize the content and enable it to exist in multiple places within a document. Contrast this with a narrative in other forms of documents where every paragraph builds upon (and thus depends on) previous paragraphs and context.

Each Technical Document instance can evolve independently and be protected by specific access rights. To be reusable, each document component needs to be constructed in a way that allows it to fit within a larger context. To achieve this, the content of each Document / Document Component will be based on an overarching schema or document structure (Section 2.2 Document Schema). This document structure helps ensure consistency and provides a mechanism for determining how individual components can fit into a larger context.

The style and layout of Technical Documents is dictated by a separate style configuration that is maintained separately but associated directly with a Technical Document Type definition. Each Document Element defined in the Schema can be referenced and have a unique set of styling parameters that are used to position and render the associated Document Element instances in each document. Style settings can be assigned to HTML output, PDF Output, and the Document Editor.

Referencing centrally controlled style settings ensure consistency in look and feel for published content and provides a convenient mechanism to update style in one location and have it automatically applied to all associated documents.

All Document Element content can have additional metadata – configured as XML Attributes - assigned to provide additional semantics for content classification and aid in content search and retrieval. This metadata is provided by the Technical Document Author when the Document Structure is designed and configured.

The Technical Documentation application, together with Aras Innovator, provide an authoring and data management environment. To make use of the content created, it needs to be exposed outside the PLM environment. The publishing/export function (Section ) provides an ability to convert the content of each Technical Document to a format more suitable to end-user consumption.

Technical Documents can be created to be used as Templates. These ‘Template’ documents can be used to create duplicate content in other Technical Documents – template content is inserted as a copy. The root Document Element of the document identifies where the content of the document can be inserted. Templates are useful when some portion of the content should be updated or extended. Authors should create a reference to other Technical Documents when that content will not be changed.

Images used within a Technical Document are managed by the ItemType tp_Image. This Item has a File Property for the 2D Image file. Tech-Doc Enabled Items will have a Relationship defined to this ItemType.