Kent Raatikainen

SEMCON

KENTUCKY CONCEPTS

2.0

KENTUCKY CONCEPTS

1

Table of Contents Introduction ............................................................................................................................................. 3

IE .............................................................................................................................................................. 3

Xml Document ..................................................................................................................................... 4

Extracted metadata ......................................................................................................................... 4

Graphic ................................................................................................................................................ 5

File ....................................................................................................................................................... 5

Map ..................................................................................................................................................... 6

Map-editor ...................................................................................................................................... 7

Version management .............................................................................................................................. 7

Major minor version ............................................................................................................................ 8

Version display formats ....................................................................................................................... 8

Status ....................................................................................................................................................... 9

Draft ..................................................................................................................................................... 9

Review ................................................................................................................................................. 9

Approved ............................................................................................................................................. 9

For Translation .................................................................................................................................... 9

Translated ............................................................................................................................................ 9

Obsolete .............................................................................................................................................. 9

State transitions ................................................................................................................................ 10

Editing .................................................................................................................................................... 10

Configuration ......................................................................................................................................... 11

Base data ........................................................................................................................................... 11

Valid Configurations .......................................................................................................................... 11

Inline configurations ...................................................................................................................... 12

Inheritance .................................................................................................................................... 13

Invalid configuration ...................................................................................................................... 13

Multiple configurations ..................................................................................................................... 13

Invalid configuration combinations ............................................................................................... 13

Languages .............................................................................................................................................. 14

Boilerplate text .................................................................................................................................. 14

Reuse ..................................................................................................................................................... 15

Information types .................................................................................................................................. 16

User information ............................................................................................................................... 16

User manual .................................................................................................................................. 16

Accessories manual ....................................................................................................................... 16

KENTUCKY CONCEPTS

2

Service information ........................................................................................................................... 16

Service manual .............................................................................................................................. 16

Fault tracing ................................................................................................................................... 16

Labor Times ................................................................................................................................... 16

Wiring diagram .............................................................................................................................. 16

Parts information .............................................................................................................................. 16

Parts catalogue .............................................................................................................................. 16

Topics ..................................................................................................................................................... 17

Templates .............................................................................................................................................. 18

Relations ................................................................................................................................................ 19

Folders ................................................................................................................................................... 20

Tasks ...................................................................................................................................................... 21

Filter....................................................................................................................................................... 22

Publishing .............................................................................................................................................. 23

Publish Version .................................................................................................................................. 23

Publish IE ........................................................................................................................................... 24

Valid from date .................................................................................................................................. 24

Custom Attributes ................................................................................................................................. 25

Mandatory or optional ...................................................................................................................... 25

Kty.include vs ieref ................................................................................................................................ 26

Translation ............................................................................................................................................. 27

Send to translation ............................................................................................................................ 27

Add translation .................................................................................................................................. 27

User rights ............................................................................................................................................. 27

KENTUCKY CONCEPTS

3

Introduction It is important to know common concepts in Kentucky.

IE A file handled in Kentucky is called Information Entity (IE). It could be an xml document, a graphic or just about any type of file.

All IEs could of course be treated as just “file”, but Kentucky pays extra attention to xml files and graphics.

The following IE-types are supported:

• Xml Document • Graphic • File • Map

Note! A task is not considered an IE

KENTUCKY CONCEPTS

4

Xml Document Kentucky parses all xml documents and extracts links and other metadata. Kentucky stores this information in the database. This way Kentucky knows if you are trying to delete something that is being referred to from another document. Kentucky also validates the xml against the xml schema.

<?xml version="1.0" encoding="utf-8"?> <ie lang="en-GB" valid-for="631" docno="D003205"> <map-concept id="D003205-A766154"> <title>Example</title> <overview> <p>This is an overview.</p> </overview> <concept> <ol> <li id="D003205-A272185"> <p>First</p> </li> </ol> <p> Goto <extref href="D003205-A272185" />. For more information see <extref href="D003134-A556963" /> </p> <p>This is a graphic</p> <figure id="D003205-A730120"> <graphic file="G003135-01-00-16.lores.jpg" /> <title>Vector graphic</title> </figure> <kty.include href="D000769-01-00-16.xml"/> </concept> </map-concept> </ie>

Extracted metadata Type Example Used for Link D003205-A272185

D003134-A556963 G003135 D000769

Resolving graphics, inclusions, xref titles

Id D003205-A766154 D003205-A272185 D003205-A730120

Acting as target for xrefs

Title Example Resolving target titles

KENTUCKY CONCEPTS

5

Graphic Kentucky generates and stores graphics in more than one format and size. Standard formats are illustrator, png and svg. Graphics are also stored as high resolution jpg (300 dpi) and low resolution jpg (96 dpi).

Illustratororiginal file

.ai

Png 300 dpi Svg

Jpg 300 dpihires

Jpg 96 dpilores

Kentucky uses a plugin (ToKentucky.exe) in adobe illustrator, to generate the formats.

File Files are treated as blobs (Binary Large Objects). No metadata is extracted and no extra formats are generated. Each file type must be registered as a template before it can be used in Kentucky. Standard file types are:

• Word (.docx) • Excel (.xlsx) • Powerpoint (.pptx) • Text file (.txt) • Pdf (.pdf) • Zip (.zip)

KENTUCKY CONCEPTS

6

Map A map is a special xml document that uses only two types of elements; folder and ieref. A map can be used to organize topics into a complete manual. It can also be used to take a snapshot of a folder structure in Kentucky. As for other xml documents, all links are extracted and stored in the database.

<?xml version="1.0" encoding="utf-8"?> <SDI docno="S000609" lang="en-GB" title="User Manual" valid-for="1"> <folder title="Introduction" level="1"> <ieref href="D000969-01-00-16.xml" kty.title="Introduction"/> <ieref href="D000964-01-00-16.xml" kty.title="IE"/> <ieref href="D000967-01-00-16.xml" kty.title="Configuration"/> <ieref href="D000965-01-00-16.xml" kty.title="Folder"/> <ieref href="D000966-01-00-16.xml" kty.title="Task"/> </folder> <folder title="Basic" level="1"> <ieref href="D000638-01-00-16.xml" kty.title="Login"/> <ieref href="D000619-01-00-16.xml" kty.title="Navigate"/> <ieref href="D000639-01-00-16.xml" kty.title="Search"/> <ieref href="D000640-01-00-16.xml" kty.title="Filter"/> </folder> </SDI>

KENTUCKY CONCEPTS

7

Map-editor Maps are edited in a special map-editor.

Version management Kentucky stores all versions of an IE in a history tree. It is possible to fetch and publish an older version.

If the IE is an xml document, Kentucky can compare two versions and display the differences.

Each version has its own status, configurations, valid from date, metadata etc.

IE

Version1.0

2014-01-01Approved

Version2.0

2015-01-01Review

Version2.1

2016-01-01Draft

KENTUCKY CONCEPTS

8

Major minor version Kentucky splits versioning into two levels.

Major version is the number to the left of the decimal 1.0, 2.0, 3.0 etc.

Minor version is the number to the right of the decimal 1.1, 1.2, 1.3 etc.

In Kentucky, major version is called “version” and minor version is called “revision”.

Minor version (revision) is incremented when status is Draft or Review. Major version is incremented when status is Approved or Translated.

Version display formats Kentucky can display the version in two different formats.

The “Alpha”, format converts the major version to a character, starting at uppercase A. The minor version starts at 1. The letter “P” (Preliminary) indicates that the IE is not approved. When an IE is approved, the minor version is not displayed.

Major version is from A to Z. When Z is passed, a second character is added => AA. Max version is ZZ. The characters I, O, P, Q and R are not used.

Status Standard format Alpha format Draft 1.0 PA1 Review 1.1 PA2 Approved 1.2 A Draft 2.0 PB1 Approved 2.1 B MAX 99.99 ZZ.99

When a new major version is created, the minor version is always reset to 0 (1 in Alpha format).

1.7 => 2.0 (PA8 => PB1).

Note! Kentucky always store versions as standard format in the database. The Alpha format is just a display format.

KENTUCKY CONCEPTS

9

Status Each IE version has a specific status. The following statuses are supported:

• Draft • Review • Approved • For Translation • Translated • Obsolete

Draft The IE is in working state and can be edited. This is the only state that an IE can be edited. In order to be able to track changes (compare) between internal progress, make a new revision.

Review The IE is intended to be reviewed by someone else. The IE cannot be edited. To edit the IE, first make a new revision.

Approved The IE has been approved. The IE can be sent for translation. The IE cannot be edited. To edit the IE, first make a new version.

For Translation The IE has been sent for translation, but not all translations have returned. The IE cannot be edited. To edit the IE, first make a new version.

Translated The IE has been sent for translation and all translations have been returned by the translator. The IE cannot be edited. To edit the IE, first make a new version.

Obsolete The IE is obsolete and should not be used anymore. Any existing links to this IE still works. The IE cannot be edited.

KENTUCKY CONCEPTS

10

State transitions Status and version can only change from a specific state. A state is a combination of status and version. Status Obsolete can be set from any status (except from “For Translation”).

Draft

Review

Approved

For Translation

Translated

Obsolete

New version

New version

New revision

New revision

Send to translation

Add translationRemove

translation

Delete translation

It is also possible to change from Draft directly to Approved.

Editing In order to edit an IE, it has to be checked out from the system. This means that you work with a local copy of the file. When the IE is checked out, it cannot be modified by someone else.

Local Cahce

Check out

Check in

KENTUCKY CONCEPTS

11

Configuration Kentucky uses configurations to filter out specific information. Another common name for configuration is “validity”, as in “this information is valid for… xxx”.

A configuration is a combination of one to eight base data values.

Base data Example of base data

Car model Model year Engine S60 2015 D2 V70 2016 D3 XC90 D4 D5 T3 T4 T5 T6 V8

If these base data were available to set individually, one could select S60, 2015, V8 but this combination does not exist and therefore is not valid.

Valid Configurations The model S60 is available with the following engines (2016): D2, D3, D4, D5, T3, T4, T5, T6.

The model V70 is available with the following engines (2016): D3, D4, T4.

The model XC90 is available with the following engines (2016): D4, D5, T6, V8.

Let’s assume that only V70 were available in 2015 (with engines D4, D5 and T4).

We also want to be able to set configurations that do not specify engine.

KENTUCKY CONCEPTS

12

Kentucky would then have the following configurations created:

[All] T6 S60, 2016, T6 2015 V8 V70, 2015, D4 2016 S60, 2016 V70, 2015, T4 S60 V70, 2015 V70, 2015, D5 V70 V70, 2016 V70, 2016, D3 XC90 XC90, 2016 V70, 2016, D4 D2 S60, 2016, D2 V70, 2016, T4 D3 S60, 2016, D3 XC90, 2016, D4 D4 S60, 2016, D4 XC90, 2016, D5 D5 S60, 2016, D5 XC90, 2016, T6 T3 S60, 2016, T3 XC90, 2016, V8 T4 S60, 2016, T4 T5 S60, 2016, T5

With only these configurations in Kentucky, a user cannot select S60, 2015, V8 because that combination does not exist.

Inline configurations It is possible to markup almost any element in Kentucky with configurations. Use Kentucky internal editor to manage inline configurations.

Note! Kentucky stores information in the valid-for attribute as comma separated numbers, not as clear text used in this manual.

<?xml version="1.0" encoding="utf-8"?> <section> <title>How to start the engine</title> <p valid-for="D2,D3,D4,D5">Special instruction for diesel engines.</p> <p>Common text</p> <p valid-for="V8">Big engine extra</p> </section>

Figure 1 Internal xml editor

KENTUCKY CONCEPTS

13

Inheritance Configurations inherit from its closes ancestor.

<?xml version="1.0" encoding="utf-8"?> <section valid-for="S60,V70"> <title>Common title</title> <p valid-for="S60,V70">No need for S60,V70 here, it's inherited from parent</p> <p valid-for="V70">V70 Only</p> <p valid-for="D3,D4">implicit union S60-D3, S60-D4, (V70-D3), V70-D4</p> </section>>

Invalid configuration Kentucky does not issue any warnings for invalid configurations.

<?xml version="1.0" encoding="utf-8"?> <section valid-for="S60,V70"> <title>Invalid</title> <p valid-for="XC90">This will never show up!</p> <p valid-for="V70">Combi</p> </section>

Multiple configurations It is possible to set more than one configuration for an IE (or inline element).

If you want to set the validity to; S60, 2016, D2 and D3, you need to select two configurations:

• S60 2016 D2 • S60 2016 D3

This is mathematical equivalent to: (S60 AND 2016 AND D2) OR (S60 AND 2016 AND D3).

Invalid configuration combinations If you combine two configurations were one is more specific than the other, the specific one does not have any effect.

• S60 2016 D2 • S60 2016

In this example D2 will never be filtered out because the second configuration says S60, 2016 and any engine. Kentucky does not issue any warnings for invalid configuration combinations.

If you set a filter to S60 2016 D3, expecting this fragment to be excluded, this fragment is included anyway.

<?xml version="1.0" encoding="utf-8"?> <section valid-for="(S60 2016 D2) OR (S60 2016)"> <title>Invalid</title> <p>Hello R2D2</p> </section>

KENTUCKY CONCEPTS

14

Languages Kentucky manages languages to be used for translations. Each implementation must have an authoring language defined. All IEs are assigned an authoring language (even graphics that may not need translations).

If a document or graphic does not exist, when publishing a specific language, the authoring language will be used as fallback.

Note! Kentucky does not issue any warnings when using a fallback language.

Boilerplate text Kentucky uses boilerplate texts for common words on each language, for example:

• Warning • Caution • Note

<?xml version="1.0" encoding="UTF-8"?> <genstrings xmlns="http://kentucky.semcon.com/schema/Genstrings"> <string name="attention.danger">Danger</string> <string name="attention.warning">Warning</string> <string name="attention.caution">Caution</string> <string name="attention.note">Note</string> <string name="attention.hint">Hint</string> <string name="attention.torque">Torque</string> <string name="copyright">© Copyright</string> <string name="target.figure">Figure</string> <string name="target.page">page</string> <string name="target.section">Section</string> <string name="target.step">Step</string> <string name="target.table">Table</string> <string name="task.postreq-text">Post requirements</string> <string name="task.prereq-text">Prerequisites</string> <string name="toc-prefix">Table of contents</string> <string name="torque-prefix">Torque</string> <string name="index">Index</string> <string name="task.task-text">Procedure</string> <string name="task.result-text">Results</string> </genstrings> This document is maintained by the Kentucky team.

Note! When adding a new language to Kentucky, a new boilerplate file needs to be created and translated.

KENTUCKY CONCEPTS

15

Reuse Kentucky is intended to manage fragments (topics) as opposed to complete manuals, and then compose manuals from topics. This reduces translation costs and time and minimize the “copy and paste” so changes reflect everywhere.

Manual 1V70, D4

1.0

Manual 2XC90, V8

2.0

Charge battery[All]1.0

Replace engineV81.0

Replace engineD2,D3,D4.D5

1.2

Replace transmissionXC90, V8

2.0

Replace engineT4,T5,T6

3.0Manual 3V70, T5

1.0

Replace engine[All]2.1

Attention[All]1.0

Changes in the Attention module will be reflected in all three manuals.

KENTUCKY CONCEPTS

16

Information types Kentucky divides information into different types.

• User information • Service information • Parts information • Training

These information types are represented as special folders in Kentucky.

User information User manual TBD

Accessories manual TBD

Service information Service manual TBD

Fault tracing TBD

Labor Times TBD

Wiring diagram TBD

Parts information Parts catalogue TBD

KENTUCKY CONCEPTS

17

Topics Topics are the basic building block of xml documents. Topics are divided into DITA-topic types:

• Map-Concept • Map-Task • Map-Fact (Reference) • Map-Overview

Topics can be grouped into larger fragments with Map-Section and Map-Book.

Map-Book

Map-Section

Map-Section

Map-Concept

Map-Fact

Map-Task

Warning

Caution

Note

Map-Section

For more information on DITA, see http://www.oxygenxml.com/dita/styleguide/webhelp-feedback/index.html.

Semcon also have an DITA training workshop, held by Robert Hinesley from the Munich office.

KENTUCKY CONCEPTS

18

Templates Templates are a way for Kentucky to store more information on IEs. Each IE is connected to a template. Common information is:

• IE Type • Original language (the language used for editing) • Xml schema • Which stylesheet to use when converting xml to html for preview • Checkout extension (i.e. .xml, .doc etc.) • Expected root element (xml only) • Which stylesheets to be able to choose from when publishing (xml only) • Extra validations (graphic only) • Rules for extracting titles and ids (xml only)

Templates are also a way to further break down topic types. A map-task can have i.e. two templates; install, remove.

KENTUCKY CONCEPTS

19

Relations Kentucky extracts standard relations from xml, i.e. xref, inclusions and graphics. Additional relations can be added via custom relations. These relations are between IEs (not versions).

Custom relations are mostly used internally in Kentucky or in online media publications.

Standard relation types:

• Is Part of • Depends On • Copied From • Replaced By • Implemented By • See Also

New relation types can be added by an administrator.

Figure 2 Relations in preview

Figure 3 IE relations

Figure 4 Relations in xml preview

When a copy is made of an IE, Kentucky automatically creates a custom relation of type “Copied From”.

KENTUCKY CONCEPTS

20

Folders Folders in Kentucky are virtual. Folders contain IEs, Tasks and other folders.

Which version of an IE to be displayed, depends on IE filter. If no filter is set, the latest version is shown.

An IE or task can be present in many folders, but it is still the same item.

Information Types, is a special folder type (structure).

KENTUCKY CONCEPTS

21

Tasks Tasks can be of different types and can be connected to IEs.

Common task types:

• Image order • Document order • Change Request • Error Report • Translation • Activity • Print Order

Task Properties:

Id Read only internal Kentucky Id Type One of:

• Image order • Document order • Change Request • Error Report • Translation • Activity • Print Order

External No Use this to map any external number from the

customer or translation agency. Title Assigned to Default is the creator, but can be changed. Priority One of:

• A • B • C • D

Highest priority is A. Default is B.

Status One of: • Not Started • In Progress • Completed • Review • Rejected • For Implementation • Failed • For Quotation

Default is “Not Started”. When status is set to “Completed”, completed % will automatically be set to 100.

KENTUCKY CONCEPTS

22

Completed % 0 – 100. When set to 100, status will automatically change to “Completed”.

Completed Date The date the task status was set to “Completed” Estimated Work Estimated work for the task to be completed Actual Work Actual work Created By The author who created the task Created Date The date the task was created

Filter Kentucky can filter information based on:

• IE Type • Status • Valid from Date • Configurations • Information type

Filter is used for publishing and navigating the tree view.

Example

An illustrator may only be interested in graphics. Setting the filter to Graphic before navigating the tree view, will filter out everything except graphics.

KENTUCKY CONCEPTS

23

Publishing Publish Version When publishing an IE from history, Kentucky automatically sets the filter according to the following properties:

• Status • Configurations • Valid from date

IE Status Filter Status Draft Draft, Review, Approved, For Translation, Translated, Obsolete Review Draft, Review, Approved, For Translation, Translated, Obsolete Approved Approved, For Translation, Translated, Obsolete For Translation Approved, For Translation, Translated, Obsolete Translated Approved, For Translation, Translated, Obsolete Obsolete Approved, For Translation, Translated, Obsolete

Figure 5 Version publish (automatic filter)

KENTUCKY CONCEPTS

24

Publish IE

Figure 6 IE publish (manual filter)

Valid from date Valid from turns into Valid to, when publishing. Any included IE with valid from date later than specified are excluded.

Topic 2 is excluded and Topic 3 will use version 1.0.

KENTUCKY CONCEPTS

25

Custom Attributes Attributes are used to add implementation specific metadata on IEs, folders and tasks. Attributes are version specific.

Attribute types:

• String • Yes/No • Date • Folder Ref • User Ref • Enumeration

Mandatory or optional An attribute is by default optional, but can be made mandatory. If an attribute is mandatory, it is not possible to save changes to an IE/Folder/Task if the attribute is not specified.

KENTUCKY CONCEPTS

26

Kty.include vs ieref Both kty.include and ieref are inclusion mechanisms. The content of the target replaces the current element. Kty.include is always resolved. Ieref is converted to xref for online media.

Use kty.include on low-level fragment inclusions, i.e. attention, inline-wrapper, section etc. otherwise use ieref.

Note! Make sure that the included IEs root element is valid at the inserted location

The current inclusion is an attention, which is allowed at the current location.

Note! Make sure that the included IE is of type xml

Trying to include an excel document, which is not allowed.

Note! Make sure not to create circular references, i.e. by trying to include the same IE as a descendant

KENTUCKY CONCEPTS

27

Translation Kentucky keeps track of all translated information.

Send to translation Does not actually send anything, just prepares and store files in a special file area on the server. The translation can be fetched by the translation agency using KTC (Kentucky Translation Client). A task of type “Translation Request” is created and the status is set to “Not Started”.

Note! Any changes in the included IEs, after this, are not reflected in the translation request

All included IE must have status Approved, ForTranslation or Translated.

Note! Any IE with status ForTranslation or Translated will not be processed.

The TA (translation agency) should not process the request until the status is set to “For Implementation”.

When the TA starts the translation process, the TA should set the status to “In Progress”.

Add translation Add translation back to Kentucky. The translation agency can use KTC or a special command line program (AddTranslation.exe).

When the TA has returned all translations, the TA should set the status to “Review”.

If the translation is accepted, the user should set the status to ”Completed”.

If the translation is not accepted, the user should set the status to “Rejected” and add a comment. The TA modifies the translation, send it back to Kentucky and change status to “Review”.

User rights Kentucky user rights:

• Document Administrator • Graphic Administrator • Folder Administrator • User Administrator • System Administrator

TODO: Describe each role