How to Configure Tech Docs
0 likes958 views
The document provides detailed technical documentation on configuring and structuring technical documents using XML schema. It covers various document types, including title, subtitle, overview, features, and component lists, with corresponding schemas defining valid elements and content. Additionally, it explains the documentation's architecture and the automated content generation process for technical documentation.
![Filters / Optional Content
Defined by server-side Method (C#)
▫ tp_GetOptionFamilies
Return JSON string in the form:
▫ “{ Filter Name: [ List of Filter Values…], … }”
© 2016 Aras aras.com
“{
"Region": [ "Africa", "Asia", "Central America", "Eastern Europe", "European Union"],
"Zone": ["A", "B", "C"],
"Model": ["X", "Y", "Z"]
}”](https://image.slidesharecdn.com/how-to-configure-tech-docs-160401180251/85/How-to-Configure-Tech-Docs-23-320.jpg)
More Related Content
Similar to How to Configure Tech Docs (20)
How to Configure Tech Docs
- 1. © 2016 Aras aras.com
- 2. Technical Documentation How To Configure © 2016 Aras aras.com
- 3. Agenda Overview of Technical Documentation Architecture Walk-through configuration of example document © 2016 Aras aras.com
- 4. Technical Document Architecture Document Types Defines all configuration options for Technical Documents ▫ Document Schema – Document Structure ▫ Content Generators – Item Referencing, Automated content creation ▫ Document Style – Document Layout for Editor and Published content © 2016 Aras aras.com Schema Style Output Settings Content Generators Document Type Technical Document
- 5. Overview Document Structure © 2016 Aras aras.com Tech DocumentTitle Subtitle Description Graphic Overview Features List Required Optional <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Marketing-Doc/> <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id =“…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Marketing-Doc/> <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id =“…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Overview aras:id =“…" > <Description aras:id =“…" > <aras:emph>Lorem ipsum dolor …</aras:emph> </Description> <Graphic-Block aras:id =“…" > <Graphic ref-id =“…" imageId =“…" /> <Label aras:id =“…" > <aras:emph>Extruder</aras:emph> </Label> </Graphic-Block> </Overview> <Marketing-Doc/> <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id =“…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Overview aras:id =“…" > <Description aras:id =“…" > <aras:emph>Lorem ipsum dolor …</aras:emph> </Description> <Graphic-Block aras:id =“…" > <Graphic ref-id =“…" imageId =“…" /> <Label aras:id =“…" > <aras:emph>Extruder</aras:emph> </Label> </Graphic-Block> </Overview> <Features aras:id =“…" > … </Marketing-Doc> Document Schema Specifies and Restricts Document Content Stored as XML
- 6. Tech Document Overview Content Generation © 2016 Aras aras.com Title Subtitle Description Graphic Overview Features List Component-List Content Generator MP2954 MP1705 MP2607 MP0138 … <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id =“…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Overview aras:id =“…" > <Description aras:id =“…" > <aras:emph>Lorem ipsum dolor …</aras:emph> </Description> <Graphic-Block aras:id =“…" > <Graphic ref-id =“…" imageId =“…" /> <Label aras:id =“…" > <aras:emph>Extruder</aras:emph> </Label> </Graphic-Block> </Overview> <Features aras:id =“…" > … </Marketing-Doc> <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id =“…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Overview aras:id =“…" > <Description aras:id =“…" > <aras:emph>Lorem ipsum dolor …</aras:emph> </Description> <Graphic-Block aras:id =“…" > <Graphic ref-id =“…" imageId =“…" /> <Label aras:id =“…" > <aras:emph>Extruder</aras:emph> </Label> </Graphic-Block> </Overview> <Features aras:id =“…" > <Components-List aras:id =“…" > <Title aras:id =“…" >…</Title> <Component aras:id =“…" > … </Component> </Components-list> </Marketing-Doc>
- 7. Tech Document Overview Document Style © 2016 Aras aras.com <div class=“Marketing-Doc“> <div class=“Title“> <span>MakerBot Replicator</span> </div> <div class=“Subtitle“> <span>Extruder #2954</span> </div> <div class=“Overview“> <div class=“Description“> <span>Lorem ipsum dolor …</span> </div> <div class=“Graphic-Block“> <img class=“Graphic“/> <div class=“Label“> <span>Extruder</span> </div> </div> </div> <div class=“Features“/> <div class=“Component-List“> <div class=“Title“>…</div> <div class=“Component“> … </div> </div> </div> Title Subtitle Description Graphic Overview Features List Component-List XML Converted to HTML CSS Applied in Browser and HTML/PDF Publishing
- 8. Document Structure XML Extensible Markup Language ▫ Storage and exchange of data ▫ Industry standard Technical Document content = XML ▫ Stored in content Property of tp_Block Tech Documents -> ItemType Document Elements -> XML © 2016 Aras aras.com <Marketing-Doc aras:id = "…" > <Title aras:id = "…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id = "…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Overview aras:id = "…" > <Description aras:id = "…" > <aras:emph>Lorem ipsum dolor …</aras:emph> </Description> <Graphic-Block aras:id = "…" > <Graphic ref-id = "…" imageId = "…" /> <Label aras:id = "…" > <aras:emph>Extruder</aras:emph> </Label> </Graphic-Block> </Overview> <Features aras:id = "…" > … </Marketing-Doc>
- 9. Document Structure XML Schema Defines the valid Elements of an XML File ▫ Defines the Document Elements of a Technical Document ▫ XML syntax Each Element is defined by: ▫ Name: element name in XML file ▫ Type: Extension of types defined by base schema ▫ Attributes: Optional – provide addt’l semantic markup ▫ Child Elements: Optional - Defines content structure/hierarchy XML Validation ▫ Compare XML content to specific XML Schema © 2016 Aras aras.com <xs:element name="Marketing-Doc"> <xs:complexType> <xs:sequence> <xs:element ref="Title"/> <xs:element ref="Subtitle" minOccurs="0" maxOccurs="1"/> <xs:element ref="Overview" minOccurs="1" maxOccurs="1"/> <xs:element ref="Features" minOccurs="0" maxOccurs="1"/> <xs:element ref="Component-List" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Title"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:text"> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
- 10. Document Structure XML Schema © 2016 Aras aras.com <xs:element name="Marketing-Doc"> <xs:complexType> <xs:sequence> <xs:element ref="Title"/> <xs:element ref="Subtitle" minOccurs="0" maxOccurs="1"/> <xs:element ref="Overview" minOccurs="1" maxOccurs="1"/> <xs:element ref="Features" minOccurs="0" maxOccurs="1"/> <xs:element ref="Component-List" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Title"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:text"> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <Marketing-Doc aras:id = "…" > <Title aras:id = "…" > <aras:emph>MakerBot Replicator</aras:emph> </Title> <Subtitle aras:id = "…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <Overview aras:id = "…" > <Description aras:id = "…" > <aras:emph>Lorem ipsum dolor …</aras:emph> </Description> <Graphic-Block aras:id = "…" > <Graphic ref-id = "…" imageId = "…" /> <Label aras:id = "…" > <aras:emph>Extruder</aras:emph> </Label> </Graphic-Block> </Overview> <Features aras:id = "…" > … </Marketing-Doc> Complex Types define Element Structures Sequences specify Order Min/Max occurrences specify Cardinality (Min/Max default to 1) Base Schema determines how content is processed Use Global Element declarations!
- 11. Document Structure XML Schema © 2016 Aras aras.com Required Optional <xs:element name="Marketing-Doc"> <xs:complexType> <xs:sequence> <xs:element ref="Title"/> <xs:element ref="Subtitle" minOccurs="0" maxOccurs="1"/> <xs:element ref="Overview" minOccurs="1" maxOccurs="1"/> <xs:element ref="Features" minOccurs="0" maxOccurs="1"/> <xs:element ref="Components" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Marketing-Doc"> <xs:complexType> <xs:sequence> <xs:element ref="Title"/> <xs:element ref="Subtitle" minOccurs="0" maxOccurs="1"/> <xs:element ref="Overview" minOccurs="1" maxOccurs="1"/> <xs:element ref="Features" minOccurs="0" maxOccurs="1"/> <xs:element ref="Components" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Overview"> <xs:complexType> <xs:sequence> <xs:element ref="Description" minOccurs="1" maxOccurs="1"/> <xs:element ref="Graphic-Block" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Marketing-Doc"> <xs:complexType> <xs:sequence> <xs:element ref="Title"/> <xs:element ref="Subtitle" minOccurs="0" maxOccurs="1"/> <xs:element ref="Overview" minOccurs="1" maxOccurs="1"/> <xs:element ref="Features" minOccurs="0" maxOccurs="1"/> <xs:element ref="Components" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Overview"> <xs:complexType> <xs:sequence> <xs:element ref="Description" minOccurs="1" maxOccurs="1"/> <xs:element ref="Graphic-Block" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element> Title Subtitle Graphic-Block Overview Features Components Description Marketing-Doc Title Subtitle Graphic-Block Overview Features Components Description Marketing-Doc Title Subtitle Graphic-Block Overview Features Components Description Marketing-Doc
- 12. Document Structure Document Element Types Text ▫ Formatted – Formatting functions on Toolbar apply ▫ Unformatted – Formatting functions on Toolbar do not apply – text only Tables – Tabular Content ▫ Row and Cell Document Elements Lists ▫ List Item Document Elements: Bulleted, Numeric, Alpha-numeric Graphics ▫ From tp_Image ItemTypes Item References ▫ Link to Item instance © 2016 Aras aras.com
- 13. Document Element Type Formatted Text Base Type: text ▫ Formatted characterized delineated by <emph> tags ▫ Bold, Italic, Underline, Strike Through, sub/super script, link © 2016 Aras aras.com <xs:element name=“Description"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:text"> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <Text aras:id =" … " > <aras:emph>Here is some </aras:emph><aras:emph bold =" true " >text </aras:emph><aras:emph>with </aras:emph> <aras:emph under =" true " >various </aras:emph> <aras:emph>formatting </aras:emph> <aras:emph italic =" true " >applied</aras:emph> </Text>
- 14. Document Element Type Table Base Abstract Type: table ▫ May only contain elements of type tr Base Abstract Type: tr ▫ May only contain elements of type td Base Abstract Type: td ▫ Defines valid content for each cell © 2016 Aras aras.com <xs:element name="Table"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:table"> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name=“Row" substitutionGroup="aras:tablerow"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:tr"/> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="Entry" substitutionGroup="aras:tablecell"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:td"> <xs:sequence> <!– or choice --> --- Valid Content of Cell --- </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
- 15. Document Element Type List Base Type: list ▫ May only contain elements of type tr Base Abstract Type: listitemType ▫ Defines valid content for each List Item © 2016 Aras aras.com <xs:element name="Features-List"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:list"> <xs:choice maxOccurs="unbounded"> <xs:element ref="Features-List-Item" /> </xs:choice> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="Features-List-Item"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:listitemType"> <xs:choice maxOccurs="unbounded"> --- Valid Content for list content --- </xs:choice> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
- 16. Document Element Type Graphics Base Type: imageType ▫ Should not have any child content Link to Items of type tp_Image ▫ Currently the only option to embed graphics ▫ User is prompted to select instance when node is placed in document Relationship to tp_Image added to document © 2016 Aras aras.com <xs:element name="Graphic"> <xs:complexType> <xs:complexContent> <xs:extension base="aras:imageType"> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
- 17. Document Element Type Item References Base Type: itemType ▫ May have child content Link to Items of type tp_Item ▫ PolyItem Add PolySources if other Itemtypes are required Narrow ItemType by adding typeId attribute Ex: ▫ <xs:attribute name="typeId" type="xs:string" fixed="4F1AC04A2B484F3ABA4E20DB63808A88"/><!-- typeId of the Part ItemType --> ▫ User is prompted to select instance when node is placed in document Relationship to Item added to document Use Content Generator to fill child elements © 2016 Aras aras.com <xs:element name="Component-List" > <xs:complexType> <xs:complexContent> <xs:extension base="aras:itemType"> <xs:sequence> <!– or choice --> --- Valid Content --- </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
- 18. Document Structure Root Elements & Content Aggregation Each Technical Document will have one or more Root Elements (Top-most XML Element) ▫ Implicitly defines document type ▫ Can be mapped to an Item Classification Identifies where each Document can be reused ▫ Document content can be reused anywhere where root element is allowed © 2016 Aras aras.com
- 19. Document Structure Root Elements & Content Aggregation © 2016 Aras aras.com Tech Document Tech Document Tech Document <Marketing-Doc aras:id =“…" > <Title aras:id ="…" > <aras:emph>MakerBot …</aras:emph> </Title> <Subtitle aras:id =“…" > <aras:emph>Extruder #2954</aras:emph> </Subtitle> <external block id ="…"> </external block> </Overview> <Features aras:id =“…" > <external block id ="…"> </external block> </Marketing-Doc> <Overview aras:id =“…" > <Description aras:id =“…" > … </Description> <Graphic-Block aras:id =“…" > <Graphic imageId =“…" /> <Label aras:id =“…" > … </Label> </Graphic-Block> </Overview> <Component-List aras:id =“…" > <Title aras:id =“…" >…</Title> <Component aras:id =“…" > … </Component> </Component-List> Required Optional Title Subtitle Graphic-Block Overview Features Components Description Marketing-Doc Title Subtitle Graphic-Block Overview Features Components Description Marketing-Doc Title Subtitle Graphic-Block Overview Features Components Description Marketing-Doc Title Subtitle Graphic-Block Overview Features Component-List Description Marketing-Doc
- 20. Document Structure Misc. Use Global Elements Use Complex Types only ▫ Elements must inherit from Aras Document Types Attributes added can be accessed in Tech Docs Editor UI ▫ Accessed in Content Generators Associate Elements with Classifications Use XML Tool for Validation and syntax check © 2016 Aras aras.com
- 21. Content Generation Defined by Methods ▫ Produces Document Element content Server-side (C#) ▫ API for producing Document Element Types Attached to Document Element ▫ Method invoked whenever: Document Element is placed in Document (Static) Document Element is placed or Document is refreshed or Published (Dynamic) © 2016 Aras aras.com
- 22. Document Style Affects Editor, HTML, and PDF output Cascading Stylesheets (CSS) XML -> HTML Rules: ▫ Document Elements - <div> Document Element names added to class attribute ▫ aras:table - <table> Colgroups added for column size adjustment ▫ Text - <span> Formatting added directly to style attribute PDF ▫ Prince XML ▫ CSS Paged Media for page-specific Settings Page Numbers, Headers, Footers, TOC © 2016 Aras aras.com
- 23. Filters / Optional Content Defined by server-side Method (C#) ▫ tp_GetOptionFamilies Return JSON string in the form: ▫ “{ Filter Name: [ List of Filter Values…], … }” © 2016 Aras aras.com “{ "Region": [ "Africa", "Asia", "Central America", "Eastern Europe", "European Union"], "Zone": ["A", "B", "C"], "Model": ["X", "Y", "Z"] }”
- 24. Example Document – Mersen Catalog Image of example document Considerations ▫ Who are the authors? ▫ Where is the information managed? ▫ How is technical content visualized? Identify Document Elements Identify reusable content Identify Referenced Content ▫ Identify ItemTypes/Properties © 2016 Aras aras.com
- 25. Title Main-Section Title Description Image-Section Graphic Subtitle Sub-Section Title List Table Description Standards Standard Mersen Document Elements © 2016 Aras aras.com Required Optional Title Mersen-Doc Main-Section Title Description OR OR Image-Section Graphic 1 1 1 1 1 1-3 0-* 1 1 Subtitle 1 Sub-Section Title List Table Description Standards Standard 1-* 0-* Color Palette
- 26. Mersen Document Elements (Cont.) © 2014 Aras aras.com Catalog Title Footnote 1 1-* 1 Content Generator Catalog-Entry 0-* Required Optional
- 27. Referenced Content Mersen Part ItemType © 2016 Aras aras.com Part String: Catalog Number String: Reference Number Integer: Number Poles String: Cable Termination Components String: Design Float: Weight String: Package CatalogEntry thumbnail Catalog EntriesString: Name
- 28. Mersen Catalog Document © 2016 Aras aras.com
- 29. © 2016 Aras aras.com