Creating Content

A Technical Document is an instance of the Technical Document ItemType. However, the design of the Technical Documentation Editor enables building documents by aggregation. That is, one Technical Document can include one or more other Technical Documents, which in turn could include other Technical Documents, and so on. Constructing documents in this manner enables content reuse, allows for the separation of content by specialty, and concurrent authoring. Because each Technical Document is a separate Item, each can have their own access rights and evolve through independent workflows / lifecycles.

The content of each Technical Document is determined by the associated Technical Document Type. The Technical Document Type defines a taxonomy; a set of Document Elements along with the allowed hierarchy and cardinality of each. For example, the following diagram describes a simple Technical Document Type.

The diagram in Figure 3 identifies the following Document Elements:

• Standard-Doc
• Title
• Subtitle
• Section
• Chapter
• TOC-Section
• TOC
• TOC-Item
• Text
• Graphic
• List
• List Item
• Table
• Row
• Entry
• ItemInfo

Each Document Element can either be of type Container, Formatted Text, Unformatted Text, Image, Item, Container – List, Container – List Item, Container – Table, Container – Row, and Container – Cell. These types are described in Section 3.2. Figure 3 also shows allowed hierarchies of Document Elements along with the number and sequence of Document Elements within them. For example, the Standard-Doc Document Element can contain the following Document Elements as direct children: a mandatory Title, an optional Subtitle, and any number (including 0) of Sections in this order. Likewise, if a Section Document Element is added, it must contain a Title followed optionally by either a Text, a Graphic, a List, a Table or an ItemInfo Document Element in any order and in any number (including 0 for each). These simple rules allow for elaborate and complex content structures.

The standard ItemType Classification property can be used to classify the content of a Technical Document. Each Classification value is assigned to the Technical Document ItemType. When used, a single Classification value can be bound to a single Document Element. When a Technical Document instance is created with a Classification value (see Figure 1 for a diagram of the Technical Document Form view) the Technical Document Element will ensure that the top-most node in the Document Element instance hierarchy for the document is set correctly.

For example, assume that an administrator added the Classification value of ‘Document Section’ to the Technical Document Element and associated that classification value with the Document Element ‘Section’. When a Technical Document is created with the classification ‘Document Section’ the Editor will automatically insert a ‘Section’ Document Element as the root in the Document and disallow any peer Document Elements. That is, there will be one root Document Element – Section – only. All child Document Elements will be restricted based on what is defined by the Technical Document Type.

Using Classification in this manner will help in the organization of Technical Document components such that they can be searched more easily. Items with separate Classifications can also have alternate Forms associated with them. When an author would like to reuse a Technical Document, they will know that documents with the corresponding classification value will contain a single root node and thus can be inserted into an existing hierarchy of Document Elements wherever Document Elements of the type of the root node can be.

Technical Documents consists of a collection of one or more Document Elements arranged in a hierarchy and sequence governed by the associated Technical Document Type. Each Document Element contains some type of content, e.g., text, images, or other Document Elements. Once the Document Element is created, the author can then proceed to add its content.

Document Elements are typically created, removed, or updated through an explicit action executed by the selection of context-sensitive menus attached to each node in the navigation pane or set of content in the editor. Only changes that are allowed at each location will have corresponding menus included. For example, given the Document Structure defined in Figure 3, once a Title is added to a Document Element of type ‘Standard-Doc’ the author can only add a Subtitle or a Section. In this case the context menu for adding content to the document after the Title Document Element is placed will be at Subtitle or a Section.

When a Document Element is selected in the content editor/viewer, selecting the key will display a context-sensitive context menu displaying the options associated with adding content at that location. For example, instead of using the right-mouse button display the context menus in Figure 4 if the author selects the Enter key the following context menu will be displayed:

The menu options displayed are for Adding content. Recall that the term ‘Add’ refers to adding peer Document Elements. The top menu item (‘Go up’) is used to display the ‘Add’ menu items for the parent Document Element. This functionality is most useful when adding content within a List.

A Technical Document consists of a hierarchy of Document Elements that collectively form a lineage of Document Elements with potentially multiple branches of arbitrary depth. There can be one or more root (or top-most) elements each containing child elements, which can in turn contain child elements and so on. The complete document element tree is exposed in the navigation pane in the editor.

The addition of Document Elements to a Technical Document is usually done in the context of another, existing Document Element. A new Document Element is either a peer or a child of the existing element. In the nomenclature of Technical Documentation ‘Adding’ refers to the addition of a peer and ‘Inserting’ refers to the addition of a child. For each existing Document Element in a document if it can have peer elements an Add sub-menu will exist in the context menu with sub-menus items for each allowed Document Element. Likewise, if an existing Document Element can have child elements, an ‘Insert’ sub-menu will exist in the context menu.

All text-based content for a Technical Document is included in one or more Document Elements. These Document Elements are configured to either include formatted or unformatted text. Note that most of the style and positioning rules for text-based content should be defined for the Document Element as part of the Technical Document Type Style. In this case, authors simply add the text, and the system applies the appropriate style (color, size, position, margin, etc.) automatically.

Once any Document Element that is of type formatted text or unformatted text is added to a document, a text entry area is added to the Content Editor with the default ‘Text…’ displayed as a placeholder. Once the author begins typing text characters, they are displayed in succession in the entry area for the element. As text is typed the text for the Document Element node in the navigation pane is updated. Any text that is too long to display in the navigation pane is truncated with an added ellipsis. When typing Text content, selecting the Enter key will result in the automatic creation of a Text Document Element and subsequent characters will be added to the new Document Element accordingly.

Formatted text can have a limited set of styling applied by the author. In general, style for text-based content should be specified by the style associated with the Technical Document Type. When any formatted text-based document is selected the toolbar for the Editor is updated to display additional buttons that can be used to apply the following style to the currently selected text (if any text is highlighted) or will apply to newly typed characters starting at the location of the cursor in the text area:

Other than symbols, the formatting options are toggles; they either are applied to newly typed text or not. Each of these can be applied collectively. For example, text can be both bold and italics. Un-applying any of these formats is simply a matter of selecting the text and selecting the appropriate format button to undo the application of the format.

Unformatted Text cannot have any additional style applied by the author. It can, however, have style automatically applied as defined by the style associated with the Document Type.

A set of additional character symbols is added to the editor and accessed by selecting the Symbol button in the editor and selecting the character button in the pop-up tooltip. These additional characters can only be applied individually to formatted text Document Elements.

In any given Document Element context, if there exists a child Document Element of type formatted or unformatted text (as defined by the Technical Document Type definition) it will be automatically inserted when the author begins to type in the editor. For example, using the document structure as defined by Figure 16, when the author places a Standard-Doc Document Element in the document and subsequently begins typing text, a Title Document Element will automatically be added, and the typed text automatically added as content. In this case, the system ‘knows’ which document element to automatically insert because the rules of the Technical Document Type describe it - a Title Document Element must exist as the first child element under the Standard-Doc element. Because this element is a text-based element, the typed text is added to the Title document element after it is added by the system. As a second example, a List Document Element contains one or more List Item Document Elements. After a List Item is added and the author begins to type text, a Text Document Element is automatically inserted, and the typed text added as content. In this case, the Text Document element is the only text-based document element for the List Item. The system assumes that when the author begins typing text that a Text Document Element should be placed.

To a certain extent, this automated behavior helps to streamline the authoring process and attempts to emulate (as much as possible) common word-processing behavior. Since the Technical Documentation Framework is a structured document application, all content must be attributed with specific Technical Document Types. Thus, any text must be included within a Document Element.

Text-based content does not include newlines/line breaks by default. This assumes that any paragraph will exist within its own Document Element. The default handling of the Enter key is to display a context menu (Section 3.2.1.1) or to automatically place a new Document of the same type when such a Document Element is allowed by the associated schema. The method for embedding a line break within a text-based Document Element is to use the Shift-Enter key combination. Doing so will result in a newline/carriage return added at the current location of the cursor.

Text content can be cut/copied from one Document Element and pasted within another. In this case, all formatting will be retained in the pasted text. In addition, text can be copied from another application and pasted within a Document Element. Text content copied from an external application will not retain its formatting. Any copied text content is pasted within the system’s copy buffer and can thus be used as a transfer mechanism to and from a Technical Document.

To copy text, select and drag the cursor using the left mouse button over the text to be copied in the content Editor/Viewer. The selected text will be highlighted. The Ctrl-C key combination will copy the highlighted text to the copy buffer. Note the Copy menu item in the document element’s context menu is used for copying the Document Element, not the selected text.

To place copied text, place the cursor within the text area of an existing Document Element and use the Ctrl-V key combination. The text in the copy buffer will be inserted at the cursor location. Note the Paste menu item in the document element’s context menu is used for pasting a copied Document Element, not the text in the copy buffer.

Lists within a Technical Document are implemented using Document Elements based on a List Type. Lists are essentially containers with an unlimited number of List Item Document Elements.

When a List Document Element is created its List Items can be rendered as either bulleted, numeric, or alpha. The default is bulleted. Selecting either a List or List Item Document Element will expose the following toolbar menu buttons. The selected option will have a box around it. All List Document Elements displayed in the navigation pane will be displayed with the List icon.

List Document Elements are expected to have child List Item Document Elements as the only element content. List Item Document Elements act as the container for all content that can be included. For example, the document structure defined in Figure 3 identifies the Document Elements that can be included in a List Item: Text, Graphic, other Lists, and Tables in any order and in any number. All List Item Document Elements displayed in the navigation pane will be displayed with the List item icon.

Tables within a Technical Document are implemented using Document Elements based on a Table Type. Tables are essentially containers with an unlimited number of Row Document Elements.

Tables in Technical Documents are restricted to be ‘rectangular’. That is, every row must contain the same number of cells/columns and every column must contain the same number of rows. This restriction is supported in the table-specific context sub-menus that are displayed in the content editor. For example, a Cell Document Element cannot be added to one Row without a new Cell being added to all Rows. As a result, only Row and Column operations are displayed in the context menus.

When a Table Document Element is added the author is presented with a dialog to choose the number of rows and columns.

The default number of rows and columns is 2, with a maximum of 10 rows and columns for each initial value.

Tables are rendered in the content viewer/editor based on the Style settings for the associated Technical Document Type. The out-of-the-box Style configuration uses a single black border with alternating background colors for the cells in even/odd rows.

Table Document Elements have specific context menus for adding and removing columns and rows. The Table context menu will only be displayed when either a Table, Row, or Cell Document Element is selected.

When adding a row or a column to a table a row/column is always added below or to the right respectively. Note that the Table context menu will be different depending on which type of Document Element is selected. In Figure 22, a Cell Document Element was selected in the content editor. In this case, the Insert context sub-menu will display a list of Document Elements that can be inserted into the cell. The Table sub-menu (as shown) displays menu items for modifying the table at that selected location in the table. For example, adding a column would add a new column between the columns with header titles ‘Heading A’ and ‘Heading B’. Adding a row would add a new row to the bottom of the table.

The Content Editor supports the ability to merge and unmerge cells in a table. Merge/Unmerge functions are applied one cell at a time. That is, to create one cell across all columns in one row, the author must first merge two adjoining cells and then merge that with neighboring cells and so on. Also, merging cells that are already merged with a neighboring row or column requires the adjoining cells to have been merged prior. Using Figure 23 as an example, to achieve the table configuration in the last step the first two cells in the second row are merged, followed by the first two cells in the third row. At this point, the first (merged) cell in the second row can be merged with the first (merged) cell in the third row.

The Unmerge function will unmerge all cells that are merged for the selected cell. That is, to apply an Unmerge function to the merged cells in the last table in Figure 23 would return the table to the original state as shown in the first table.

Text content within a Technical Document can be linked to any Document Element within the same Technical Document or within a separate Document Element. In addition, text content can also be associated with a URL, like a hyperlink in an HTML document. Both types of links behave similarly when the content with these links are exported/published (see Section 4). Once the link is created, the Content Editor can be used to explore the linked content. Links between Document Elements establishes a Relationship between the two corresponding Technical Document Items. Thus, linked Document Items cannot be removed if they are the target of an existing link.

To create a link to a Document Element:

1. Select the text from within an open Technical Document in Edit mode.
2. Place the cursor over the beginning of the text and drag with the left mouse button pressed to dynamically select all text characters/words associated with the link.
3. Select the Create Link button in the toolbar.

The Link Editor Dialog will be open and display the contents of the currently opened Technical Document at the top.

4. Select the Document Element from the current document to set as the link target or search for another document using the search grid at the lower portion of the Link Editor Dialog

Document Elements are selected the same as in the Editor; either by selecting a node in the Navigation Pane or selecting the element in the content viewer. If another document is searched, select the Open Document button (green check mark) above the search grid to display the selected document.

5. Select the Accept button (green check mark) at the top of the dialog to accept the link target

Doing so, will close the Link Editor Dialog. The text used for the link in the source document will be highlighted to indicate that the text is associated with a link.

1. To create a link to a URL:

Select the text from within an open Technical Document in Edit mode.

2. Place the cursor over the beginning of the text and drag with the left mouse button pressed to dynamically select all text characters/words associated with the link.
3. Select the Create Link button in the toolbar
4. Select ‘URL’ from the Link Type combo box in the top portion of the Link Editor (Figure 11)
5. Type the URL for the link in the text edit box.
6. (Optional) Select the Check URL button to open a separate browser window using the URL that was typed

Once a link has been created, the target content can be modified by selecting the Edit Link button on the toolbar. This button, along with the Test Link and Remove Link buttons, will be displayed when text containing a link is selected in the content editor.

When the Edit Link button is selected, the Link Edit Dialog is displayed. At this point, the author can select the Document Element (or URL) to use like the steps in Section 3.2.7.1 and Section 3.2.7.2. To test a link, select text containing a link and select the Test Link Button. The Link Edit Dialog is displayed with the Technical Document (containing the target Document Element) shown and the Document Element target selected. If a URL was used for the target, a browser will be opened to the selected URL. Item Document Elements Item Document Elements are Document Elements with a Relationship to an Item within Innovator. A Relationship (of type tp_ItemReference) is created between the Technical Document and the selected Item. A referenced Item can be either a Part, Document, or CAD Document. Administrators may choose additional items that a Technical Document can display. For more information, refer to Aras Innovator 33 – TDF Administrator’s Guide. When an Item Document Element is added to a Technical Document, the author is prompted to select an existing Item. Adding Document Elements of this type to a Technical Document enables the author to establish a direct relationship to Items that, presumably, the document is written for. Once included in a Document, the author can view the associated Item by selecting the node of the Item Document Element instance in the Navigation Pane and select the ‘View Item’ sub-menu. Doing so will open the main Form associated with the Item. Nodes of this type will be displayed in the Navigation Pane using the icon associated with the related Item. Item Document Elements typically have Content Generators associated with them (Section 3.6). In this case, the content created by the Content Generator is added to the document automatically. Item Document Element instances together with Content Generators allow authors to quickly and efficiently created document content dynamically and enable the synchronization between the two.

Mapped Property Document Elements are a type of Unformatted Text Document Element that are used to reference a Property of an Item referenced by an ancestor Item Document Element. When authors place instances of a Mapped Property Document Element, the system will automatically apply the content of the associated Property of the referenced Item. Mapped Properties are configured with Document as part of the associated Document Type. Mapped Property Document Element have two Attributes: ‘Property’ and ‘Mode’. The Property attribute specifies the name of the Property that is mapped. The Mode attribute specifies whether the Property (and thus the related Item) can be modified within the Technical Document.

Figure 1: Attributes Dialog for Mapped Property Document Elements Mapped Property Document Elements are edited using a pop-up Form in the Technical Documentation Framework. To edit a value, select the Document Element in the Editor or Tree View and/or double-click to display the Property Editor Form. Document Elements with a grey, dotted border can be edited. Document Elements with a red, solid border are read-only. For example:

Figure 2: Mapped Property Editor Form

Values can only be changed using this Form. Selecting the ‘Check’ button will update the Mapped Property Document Element in the technical Document only. Authors will see a pencil icon (

), signifying that the Property of the referenced Item has not been updated, next to the Document Element in the Tree View. The referenced Item will be updated when the technical document is saved, in which case the pencil icon will be hidden. Selecting the ‘X’ button will cancel the update without any changes to the technical document.

Selecting the pencil icon (

) in the Tree View will prompt the author with a Dialog to discard the updated Property. In this case selecting ‘OK’ will revert the modified Property(ies) to their previous value.

The following Property Value Types are supported:

1. String
2. Text
3. Numeric (Integer, Decimal, etc.)
4. Date
5. Boolean
6. Item
7. List
8. Image (Display only - Editor not available)

The Edit Field in the Property Edit Form is based on the Property Type. For Text and Numeric Fields, an attempt to set a value that does not match the type will result in an Error being displayed in a Dialog.

Figure 3: Mapped Property Edit Forms Modifying a versionable Item vis-à-vis Mapped Property Document Elements will result in the referenced Item to be versioned automatically. Since Technical Documents refer to Items via fixed Relationships, the Item Document Element will show as stale since it will refer to the previous generation of the Item.

Image Document Elements refer to any 2D raster or vector-based image that is supported by Innovator. All graphical content for a Technical Document must be stored as a separate Graphic Item. The Technical Document Application includes a ‘Graphics’ TOC folder that includes Graphic instances. Graphics have the following Form:

To add an image to a Technical Document, Add or Insert any Image Document Element Type. The user will be presented with a Search Grid for Graphics. Selecting an instance will add the corresponding image content at the selected location with the document. In addition, a Relationship is added between the Technical Document and the selected Graphic.

Image Document Elements can be added, and the corresponding Graphic Item automatically created, while pasting an image into the Editor View. The process is as follows:

1. Select an image and copy it to the clipboard. Note that the image itself needs to be copied; not the image file
2. Select Document Element after which you wish to place the new Graphic. Note that if a Container Document Element is selected, the system will check whether a Graphic Document Element can be added as a first child. If so, the new Graphic will be added as a child.
3. Select Ctrl+V (Paste) to start the process
4. The system will display a Graphic Item Form Element with the image was selected
5. Fill out the Form as required
6. Select Ok to create the Graphic Item and place the new Image Document Element
7. Select Cancel to cancel the operation. In this case, a new Graphic Item will not be created.

Image Document Elements can be added, and the corresponding Graphic Item automatically created, while dragging an Image File from the local file system into the Editor View. The process is as follows:

1. Select an image an image file from the local file system and drag (with left mouse button held down) the file onto the Editor View.
2. The system will display a thumbnail image with the cursor as the file is moved/dragged over the contents in the Editor View. A blue or orange will display between the content to identify valid or invalid drop locations respectively.





3. Lift the left mouse button when the desired location is found.
4. The system will display a progress dialog showing the file upload operation. Selecting Cancel within this dialog will cancel the operation and no Graphic Item will be created. Once the image file has uploaded the system will display a Graphic Item Form Element.
5. Fill out the Form as required
6. Select Ok to create the Graphic Item and place the new Image Document Element
7. Select Cancel to cancel the operation. In this case, a new Graphic Item will not be created.

The Document Editor will automatically add, or merge Text Document Elements based on the selection of the Enter, Backspace, or Delete keys. This is to provide a text editing experience like a traditional text editor or word processing software. For Text Elements, selecting the Enter Key while editing text within a sentence will automatically create and append a separate Text Document Element and place the cursor at the beginning of the line. Any text that exists after the cursor will be removed from the previous Text Document Element and pasted in the new Text Document Element. Similarly, when a Backspace Key is selected while the cursor is at the start of a Text Element will automatically cut the text from the current Document Element, paste it at the end of the previous Text Document Element, and remove the current Text Document Element. This operation is only done if there exists a preceding Text Document Element. The Delete Key executes in a similar way but only when the cursor is at the end of a Text Document Element and there exists a following, peer Text Document Element. Thus, these actions execute in a manner similar to how paragraphs are automatically split or merged in a typical text editor. For Text Document Elements that are the last child of a List Item Document Element, selecting the Enter Key will result in the creation of a new List Item Element, with a Text Document Element child and place the cursor in the next Text Document Element. Any text that was after the previous cursor location will be cut and added to the new Text Document Element. Thus, these actions execute in a manner similar to how items in a list are created in a typical text editor.

Filters provide a mechanism for Technical Document Authors to associate Characteristics (metadata) with Document Elements and use these characteristics to automatically filter the content. This is useful when technical documents can serve multiple, but related, purposes. For example, a technical document that describes several similar models of the same part. Content that is specific to any model (or models) can have filters associated with it. When an end user wishes to see only the content that is either associated with all models or is particular to a specific model, they can identify the appropriate filters and the Technical Documentation Framework will display the correct content accordingly.

Referring to Figure 28, the list of features associated with Model ‘X123-01’ is A, B, and D. The list of features associated with Model ‘X123-02’ is A, C, and D. The list of available Filter Names and associated Filter Values is set by the Technical Document Administrator and exists for all Technical Document Types. By default, the following Filters are included: Region, Zone, and Model.

To add a Filter to a Document Element, right-click the Document Element either in the Navigation Pane or in the Content Viewer and select Change Condition. The Change Element Condition dialog is displayed.

The Change Element Condition dialog will display each Filter that has been configured for the Technical Documentation Framework. Each Filter Name is displayed with a combo-box list containing each of the corresponding Filter Values. In Figure 29, the ‘Model’ Filter has the following Filter Values: ‘X’, ‘Y’, and ‘Z’ with the Filter Value ‘X’ selected. If this were the only Filter selection, then the selected Text Document Element would have the Filter ‘Model: X’ associated with it.

A set of Filters can be applied to the entire Technical Document. To do this, right-click the root node in the Navigation Pane (it will be displayed at the top with the name of the document) and select Change Condition in the context menu. Document Elements with associated Filters associated with them are displayed in the Navigation Pane with a Filter icon added to the right of the node. This alerts the author that the corresponding content could be disabled or hidden with the application of a Filtered View.

A Filtered View contains content that is either hidden or disabled based on the application of one or more Filters. The set of Filters is applied to all content that is displayed in a Technical Document, including referenced content. Only Document Elements that have a Filter applied will be affected by a Filtered View. This is because the system assumes that content without Filters apply to the set of all Filters. To create a Filtered View, select the Document View button on the toolbar. Doing so will display the Document View dialog. The Document View dialog provides a list of all Filters showing each Filter Name and corresponding Filter Values in a combo-box list. To apply a Filter to the view, select the check mark next to the Filter Name. This will enable the list of Filter Values.

The Filter Values that have been assigned to Document Elements in the current Technical Document will be highlighted (in color) in each list. To apply a Filter Value, select one or more Filter Values in each list and select the Apply button. By default, content that doesn’t apply to the selected list of filters is displayed as disabled. Document Elements that have been disabled in a Filtered View will be displayed lighter (partial transparency) in the Navigation Pane and as a collapsed section in the content viewer with the Filtered Icon displayed to the right (Figure 32). To expand the disabled section, select the ‘+’ button next to the disabled content in the content view. Selecting the Filter Icon to the right of disabled content in the Content Viewer will display the Change Element Condition dialog for the Document Element. In this case, the author can change the associated Filters for the disabled Document Element.

To hide disabled content in a Filtered View, select the radio button next to the ‘Hidden’ label in the Document View (Figure 31). In this case, disabled content will not be shown in the Content Viewer. The Document View dialog allows the author to select a set of Filters for a Filtered View. To turn on/off a Filtered View, select the Enable Filter button in the toolbar. Note that this button is selected by default when the user selects the Accept button in the Document View dialog.

Grouping Document Elements allows for a set of Filters (Section3.5) to be applied to all content within the Group. Grouped content is displayed in the Navigation Pane using the Group Icon with all content within the group displayed as direct child nodes. There is no visual indication in the Content Viewer for grouped content. Any contiguous set of Document Elements can be grouped that exist within a Document.

To Group Document Elements, select each in the Navigation Pane using the left mouse button while holding down the Control Key. Note that only contiguous Document Elements can be grouped. When all Document Elements are selected, right-click on one of the selected Document Elements to display the context menu and select Group. Any grouped content can be ungrouped by right clicking the Group Document Element and selecting Ungroup in the context menu.

Technical Document content can be an aggregation of multiple Technical Documents, which in turn can contain other Technical Documents and so on. The result is a hierarchy of document components. Individual Technical Document components can be reused in other Technical Documents and be edited concurrently with the documents that refer to them. A Relationship instance is created between the source document (document which includes the reference) and the target document (containing the external content). When reusing document content, it’s important to keep in mind that the Technical Document Type of the document including the content must be valid. This means that the root nodes in the document to include must be able to exist at the location in the source document that they will be placed. For example, if a Table was going to include external content for its rows, each document that is included must only contains Row Document Elements as its top-most Document Elements. For each Technical Document, the system will store the name of the top-most (root) node in the document if there is only one. Otherwise, it will the term ‘multiple’. Documents with multiple root nodes are harder to reuse, especially if the root nodes are not the same type. This is because the sequence and type of root nodes must conform to every document that they are being reused in. For this reason, it is generally beneficial to only have a single root node for any Document that the author intends to reuse. If not a single root, then have all root nodes be of the same type.

At any location where either a child or peer Document is allowed, the context menus will include a sub-menu entitled ‘External Content’ (Figure 17 and Figure 18). Selecting this menu item will display a search grid for Technical Documents. The searched content will be filtered by Documents that use the same Technical Document Type and that include root nodes of a type that can be added (or inserted as the case may be) where the author has chosen to add the content. The author adds whatever additional search criteria as is necessary and selects the Technical Document instance to add.

External content will display in the Navigation Pane as a separate node using the name of the Technical Document that is included. Using Figure 33 as an example, the Technical Document ‘Standard Document Example 3’ was inserted. Note that the Document Element Standard-Doc must have a Title Document as the first child, an option Subtitle as the second child and any number of Section Document Elements that follow. Since the Technical Document that was inserted had a Section Document Element as its root, it was a candidate for insertion at the location it was inserted. In the Content Editor, the added external content looks identical to the content that exists within the document.

Any external content that is referenced can be brought into a document as permanent content. In this case a copy of the content of the referenced document is added to the source document, replacing the reference. To copy the contents of a referenced document to the location where it is referenced, right-click the External Content Document Element in the Navigation Pane and select Make Internal.

The external content converted to internal is grouped using a Group Document Element. This can then be ungrouped. See Section 3.4.1.

A separate Technical Document instance can be created from selected Document Elements. This is useful when the author realizes that there is content within a current document that can be reused in other documents. To create a Technical Document using selected, contiguous Document Elements select the Document Element(s) using the left mouse button. To select multiple Document Elements, hold down the Control Key while selecting each Document Element. Right-click on one of the selected Document Elements and select Make External. The following dialog will be displayed:

Provide the Name and Document Number for the Technical Document and select OK. After selecting OK, save the original document at which point the external Technical Document will be created and the external reference between the two documents created.

By default, all referenced document content cannot be edited within the context of a Technical Document that references it. Changing this content would thus require opening the associated Technical Document Item and editing the content from there. However, it is possible to enable referenced content editing in one of two modes: Implicit or Explicit.

Implicit Edit Mode allows authors to edit referenced content as if the referenced content was part of the opened document without any need to lock this content prior. In this mode, when the parent (or opened) document is saved, the referenced document content is locked, updated, unlocked in a continuous series of steps for any referenced document content that was changed. Referenced Technical Document Items are not kept unlocked after save or update operations. Explicit Edit Mode will also allow authors to edit referenced content but will require that the associated Technical Document Item is first locked for Edit. This can be done directly in the Technical Document Editor or separately as is part of normal Lock/Unlock operations in Aras Innovator.

Example Edit Command in Context Popup Menu Explicit Edit Mode also requires that referenced Technical Document Items be unlocked when the author has completed their updates. This can be done within the Technical Document Editor or separately as part of the normal Item Lock/Unlock operations in Aras Innovator.

Example Save, Done Editing, Discard Changes Command in Context Popup Menu In Explicit Mode, referenced and locked Technical Document Items are saved when the parent document is saved. Authors can also save referenced document content directly using the context popup menu. Users will know the Edit Mode that has been configured based on the existence of the Edit, Save, Done Editing, and Discard Changes menu options in the context menu. When a referenced document is claimed or locked by a separate User, the Technical Document Editor will display an icon for the node associated with the referenced document in the Structure Tree.

Example of Locked Referenced Content Hovering the mouse over the icon will display the name of the User who has the Technical Document claimed or locked. Any referenced document content that has been changed and not saved will also cause the display of an icon in the Structure Tree as an indication that the content has not been saved. Referenced document content is distinguished visually by a solid bar displayed to the left of all content within the referenced document. In addition, when referenced document is editable, the content will be displayed in the same font color and opacity as all other content that exists within the opened Document. By contrast, when referenced document content is not editable, it will be displayed in a different opacity, which appears to the user as a slightly different color.

Example Technical Document with Non-editable Referenced Document Content

Example of Unsaved Referenced Content Using Implicit Mode editing, it is possible that referenced content can be changed/saved independent from the changes made to a Technical Document that references it. The Technical Document Editor will track the modification timestamp of all referenced content and compare that to the actual Item before an attempt is made to update the referenced Technical Document Item. When a discrepancy is found, the user will be prompted with the following dialog:

Warning Dialog for Stale Document Content Selecting Save will overwrite changes made to the referenced document. In Implicit Edit Mode, saving will cause the referenced Document Item to be locked, updated, and unlocked in one series of steps. Selecting Discard Local Changes will remove the changes made and revert to the latest. Selecting Cancel will cancel the Save with no update to the referenced document content.

Technical Documents have provisions to support storage and management of multiple language instances of document content. The content for each supported language evolves with the original. The assumed process is that a Technical Document is authored in one language (the default language) with 0 or more additional translated versions of this content stored with the document. Translated content is immutable; only the original default content will be edited by the author. The concept is shown below:

Referring to Figure 36, authors will create and update document content as part of their organization’s normal workflow. At some point the document content is deemed complete and hence ready to be translated. The Technical Documentation Framework does not have the capability to translate between languages. This must be done by an external process or service. There is also no ability for the Technical Documentation Framework to verify the correctness or completeness of translated content. Once the translated content is complete, it is stored with the original Technical Document in language-specific properties.

Support for additional languages and locales are configured as part of standard Innovator configuration. Note that the language and locale settings for the user’s browser also affect how content is edited and displayed. Additional language names will be included in the language selection combo-box list in the toolbar. The content of the displayed language is loaded into the editor. Note that only the default language is editable; all others are treated as read-only.

One of the main features of the Technical Documentation Framework is its ability to reference Business Objects (e.g., Parts, Requirements, Processes, etc.) stored in Innovator and include this information within a Technical Document. These Business Objects (Items) are tied directly to each Technical Document that refers to them using standard Innovator Relationships. This binding allows users to see which Business Objects are related to each Technical Document and which Technical Documents relate to each Business Object using the Structure Browser. Technical Documents store the revision of each Business Object they are bound to so that when Business Objects evolve to subsequent revisions, authors can be notified and there’s visual indications provided by the Editor when bound items have changed (see Section 5.1). In addition to this reference, property data from these Business Objects (and/or related Items) can be queried and used as Technical Document content as information in tables, lists or however is needed. Including information in this manner requires a Content Generator. Custom content generation refers to the process of using configured Methods to generate XML content to be used within Technical Documents. The intent is to provide a mechanism to reference content from existing Items within Innovator or produce content as the result of a programmatic algorithm (or both) and provide this data in a format suitable for a Technical Document. Note that the term ‘suitable’ refers to content that respects the underlying document data model (schema). Content Generators (the Methods that produce document content) can be used to create and store data statically within the document or dynamically with the content stored temporarily. In the former scenario, the Content Generator acts like a macro, automating the production of content. In the latter scenario, the Content Generator acts more like a reporting engine with the resulting content representing the most up-to-date information. Also, note in the latter scenario the generated data is transient; existing only until the content is regenerated, the document is published, or the document is closed in the Technical Documentation Framework.

Content Generators are triggered by the existence of a Document Element in the document that has been mapped to the Content Generator Method in the Document Configuration. Referring to ’Standard’ Document Type, the ItemInfo Document Element instance has been mapped to a Part. The Content Generator queries this part for various properties, which are then displayed in a Table Document Element.

The process works as follows:

1. The author places a Document Element within the document that has been mapped to a Content Generator
2. If this is an Item Document Element, the user will be prompted to select an Item to reference.
3. The configured Content Generator Method is called on the server to generate the Document Elements to add (as children) to the Document Element added by the author
4. The generated content is stored in the Document on the client
5. When the author saves the Technical Document, the generated content is added to the data on the server. Note that the generated content exists only on the client until it is saved.

Generated content is treated like other content created directly by the author. It can be copied and reused in other places within the document and within other Technical Documents, it can be modified, and removed. Note, however that generated content can be regenerated. Doing so will overwrite all content modified by the author.

Document Elements can be rearranged within a document, that is open for editing, via Drag and Drop (DnD). DnD refers to the movement or relocation of a selected Document Element by moving/dragging the Element from its current location while holding down the left mouse button and dropping the element to its new location by releasing the left mouse button.

Moving Document Elements using the editor is as follows:

1. Select and hold the Shift button
2. Select, using the left mouse button, a single Document Element within the Editor
3. While holding down the left mouse button begin moving/dragging the cursor. At this point, the View of the selected Document Element will change to show the Document Type and its corresponding icon.



4. Move the selected Document Element to a separate location within the document, and within the Editor View



Notice that the selected Document Element is rendered as transparent and that there is a blue or orange Bar displayed at various locations based on the location of the cursor throughout the process of dragging. Blue lines indicate valid locations for the selected Document Element as defined by the Document Schema. Orange lines identify invalid locations. In which case, the selected Document Element cannot be moved/dropped there.

5. Select the location to move the selected Document Element by releasing the left mouse button
6. The system will remove the Document Element from its previous location and place it within the selected location

Referring to the previous section, a similar process can be used to copy a selected Document Element by holding down the Ctrl Key instead of the Shift Key. The result will be a copied Document Element at the chosen location.

Document Elements can be moved via the Navigation Pane using DnD. The process is as follows:

1. Select the Document Element node in the Navigation Pane. Note that it is not necessary to simultaneously select the Shift button as is done when moving within the Editor
2. While holding down the left mouse button begin moving/dragging the cursor. At this point, the View of the selected Document Element will change to show the Document Type and its corresponding icon.



3. Move the selected Document Element node to a separate location within the Navigation Pane



Notice that the selected Document Element is rendered as transparent and that there is a blue or orange Bar displayed at various locations based on the location of the cursor throughout the process of dragging. Blue lines indicate valid locations for the selected Document Element as defined by the Document Schema. Orange lines identify invalid locations. In which case, the selected Document Element cannot be moved/dropped there. When dragging the Document Element over a Container Document Element Node, the Container node is rendered with a blue box around identifying that it is valid to place/drop the selected Document Element as a first child within it.

4. Select the location to move the selected Document Element by releasing the left mouse button
5. The system will remove the Document Element from its previous location and place it within the selected location

Referring to the previous section, a similar process can be used to copy a selected Document Element by holding down the Ctrl Key and dragging within the Navigation Pane. The result will be a copied Document Element at the chosen location.