Enhancements to the Technical Document Framework
The Aras Technical Documentation application has been a powerful tool for creating technical publications with multiple data sources quickly while reducing the chance for errors related to copying data. The Technical Document Framework (TDF) is available to all Aras users, and can be downloaded and installed using the Aras Update Utility. The TDF enhancement we’ll cover today (introduced in 12.0 SP4) enables users to create and use existing Tech Doc-enabled content as a template in another Tech Doc. The template Document is added to the target Document as a full copy. Using this feature, a common element in your Tech Docs can be made into a template that can be reused, and multiple templates can be used to create modular documents. In this example, we’ll go over the steps required to create a custom Tech Doc template and then insert it into another Technical Document Item. Creating the Template We’ll start by creating the template, we can create our Tech Doc template just as we would any other Tech Doc: Go to Technical Documentation > Technical Documents in the TOC Right click and select Create New Technical Document Fill out the form’s required information: Document Number – ‘Tmpl-01’ Name – ‘TDF Template’ Schema – Standard Save (but don’t close) the new Tech Doc Once saved, the tab for the Tech Doc Editor should be added to the brown column on the left, click on that to open the editor. For now, let’s keep this template and explanation simple and just add a title and a table. In the Document Tree column on the left side, right click on the area labeled TDF Template (the root element) Click Insert > Title then type to fill the yellow region that is added to the editor to the right Right click on the Title element in the document tree and select Add > Table In the resulting dialog, set both to the row and column attributes to 3 then click OK Confirm that the table is added to the editor area and to the left column as a collapsible tree with three child rows, each with three child entries Click on the first column and row in the table and start typing in the first header box, then click to the next column or tab through to fill out the table Click Save and Close and to finish the template Adding the Template to a Document Next, we’ll make a new Technical Document. As before: In the TOC, go to Technical Documentation > Technical Documents Right click and select Create New Technical Document In the form, enter in the required fields: Document Number – ‘Doc-01’ Name – ‘TDF Document with Template’ Schema – Standard Save the Tech Doc, then click on the editor tab Add two section elements by right clicking on the root element and selecting Insert > Section. The sections will each be added with a child title element Fill out the first section: Type in a title for the first section Right click the title element either in the document tree or in the editor and select Add > Text twice Enter some filler text in both text fields using the editor Add a title to the second section, then right click on the section element in the document tree and click Add > From Template In the item selection dialog, search for the template document, select it, and click OK Save and Close the Tech Doc There are a few things to note. For a template to be added to a Tech Doc, both must use the same the schema. Additionally, adding elements "From Template" differs from adding "External Content". With external content, the elements of the source and target documents are identical and cannot be changed independently. When adding from a template, the elements are inserted as a copy, so the source and target documents can be modified without affecting the other Here’s what the final result should look like: Closing Remarks The Technical Documentation Template enhancement works with previous methods of customizing your Tech Docs, allowing us to create new Documents faster than ever. If you want to continue taking full advantage of the power of Tech Docs, be sure to check out some of our previous blogs that go into detail about custom content generators and adding links to Documents. Additionally, we have compiled a collection of custom Technical Document examples on this Github repo for implementation ideas.The Mapped Document Elements Enhancement
Mapped Document Elements (MDE) are a core feature added to the existing Technical Document Framework (TDF) application, released in Aras Innovator Version 12 Service Pack 5 for all users. This enhancement allows for the association of Document Elements in a TDF-enabled document to a Property of a referenced Item. A Document Element to Item Property association means that the properties of the Item in the Tech Doc will update as the Item’s property is updated. Additionally, the Element can be flagged with ‘write’ permissions to allow for editing and saving the Property value directly from the Tech Doc. MDE is a useful feature for ensuring a Tech Doc’s references to an Item stay updated as the Item’s properties are changed. One application of this feature is documenting the most recently calculated cost of Parts in an assembly. This blog post will cover enabling MDEs for Part Items and mapping a Part Item’s name property to a Technical Document. Enabling Mapped Document Elements in TDF By default, the new Mapped Document Elements are not included in the Standard schema, to prevent any unexpected behavior with existing ItemInfo Elements in Tech Docs. We’ll need to create a new schema to utilize the enhancement. Go to Technical Documentation > Document Types in the TOC Right click and select Create New Document Type Fill in the name field with ‘MDE Enabled’ In the content section, copy and paste this code: gist.github.com/.../24420dfa39e6af880ce0a17f456c56f1 In the Stylesheet tab, click Add New Document Style Enter the name ‘MDE Enabled Stylesheet’ Right click and select Stylesheet > Open In the style section, copy and paste this code: gist.github.com/.../3d5e5e5eaecbd8c302874fea7fb1ea2a Click on the Validate button, the schema should be valid Click Done to save Adding an MDE to the Document Now that the schema is made, we can start to build our Tech Doc. First, we’ll want to create a Tech Doc that uses our new Schema: Go to Technical Documentation > Technical Documents in the TOC Right click and select Create New Technical Document Fill out the form’s required information: Document Number – ‘MDE-0001’ Name – ‘MDE-Test’ Schema – MDE Enabled Save (but don’t close) the new Tech Doc Click on the Tech Doc Editor tab that was added to the left side column From the Editor tab, we can start adding elements to our Tech Doc. Adding a Mapped Document Element is like adding any other Element to a Tech Doc, with some additional steps for selecting the specific Part. Just follow the steps below: Right click on the root element and select Insert > Item Info > Add Item. In the dialog, search for and select the desired Item, then click OK Right click the ItemInfo entry in the tree and select Insert > PartStatement > Add Item. In the dialog, search for and select the desired Item, then click OK Right click the PartStatement entry and select Insert > Any Property Right click on the AnyProperty entry and select Edit Attributes to open a dialog In the property field, enter ‘name’ Select ‘write’ for the mode Click apply Save (but don't close) the Tech Doc While the Tech Doc is claimed and in edit mode, you can double-click on the Property in the editor pane to open a pop-out field editor. When selected, an MDE with write permissions will have a gray dashed border, while a read-only MDE will have a solid red border. Changes made in that field can be added or discarded by clicking on the check or x boxes, respectively. Once a change is made, the element in the tree and its parent element will be marked as changed with a pencil icon; clicking on that icon will open a dialog prompt to revert the changes. To save any changes made to an Item, just click Save or Done. On a save, any changes to Properties will be validated by the system. Additionally, if changes have been made outside of the Tech Doc, the property in the editor will be highlighted with a red dashed border. The right click menu on the PartStatement tree element will now contain a Version menu, which gives you option to update the data to reflect the latest version, ignore the current version, or ignore this and all new versions and changes. We’re excited to share this enhancement to the Tech Doc Framework; this core feature will enable other new features in future Requirements Engineering and Technical Documentation application releases. To take advantage of the range of options available in Technical Documents, check out our previous blogs that cover other ways to customize your Tech Docs, such as custom content generators, adding links to Documents, and creating templates. We also have a GitHub repo with a number of custom Technical Document examples to use as ideas for your own Tech Docs.
