1 | VARIAN ONCOLOGY SYSTEMS

VARIAN

ONCOLOGY

SYSTEMS

MUCH ADO ABOUT TEMPLATESReduce the learning curve and increase productivity at DITA implementation

CATHERINE LONG

SENIOR TECH WRITER

NOVEMBER 2017

2 | VARIAN ONCOLOGY SYSTEMS

Varian Medical Systems, Inc.

Varian is a global medical device company which is

FDA regulated.

Product Support Engineering (PSE)

➢Service documentation for 3,500 internal users, as well

as some customer documents.

➢Most document types require a security – applied to the

PDF after released from the CMS.

➢Many documents are an integral part of the design

history file.

➢Most documents are rush and need to be released

ASAP.

➢DITA implementation is in process. #LavaCon

3 | VARIAN ONCOLOGY SYSTEMS

PSE Document Statistics

In service you

never know

what document

type for what

equipment and

by which

content

developer will

be needed

when.

100 content developers – authors

10 Microsoft Word templates

60 document types

700 new documents per year

800 revisions per year

3 document process admins

#LavaCon

4 | VARIAN ONCOLOGY SYSTEMS

PSE DITA Training

- How to recreate various documentsDilemma 1• To transition from unstructured Word to structured DITA XML with

no notice of what document type will be needed next.

- How to train many content developersDilemma 2• The content developers are not technical writers. They are remote

service engineers who primarily support products in the field and do not have time to master a new authoring tool.

- How to QA with limited resourcesDilemma 3• The current process includes a technical review and a basic

format review. Moving to a structured tool with specific transformation requirements necessitates different QA.

#LavaCon

5 | VARIAN ONCOLOGY SYSTEMS

Templates to the Rescue

Templates simplify the transition to DITA XML by

providing an implementation plan that can be set up

before transition and tested with a pilot. They also

provide the following:

✓ Act as a ready made outline

✓ Include specific required metadata

✓ Simplify XSLFO transformation requirements

✓ Streamline schematron implementation

✓ Solve the three main dilemmas#LavaCon

6 | VARIAN ONCOLOGY SYSTEMS

Specialization vs. Templates

Specialization

• Requires higher level of resources = Consultants

• Need for coordination increases due to shared environment with Tech Pubs team

• Requirements need to be more fully established at pre-implementation

• Smaller team of authors and contributors = easy consensus

• Plan is to evaluate the need to specialize

• Templates give us a “pilot” for establishing goals for specializing

Templates

• Oxygen provides quick and easy creation and editing

• In-house expertise can be used

• Service document type variations and rate of change is high

• Processes in field are more fluid than manufacturing

• Regulated industry

• Allow for a more streamlined change process to close out complaints

• Provide for quick changes based on feedback and from large author and user base

7 | VARIAN ONCOLOGY SYSTEMS

– recreate various documents

Multiple bookmap templates for various document

types

• 6 templates with 2 main structures

✓ 2 bookmaps with maps to create chapters for longer

documents – manuals: installation, calibration, maintenance,

part replacement, etc.

✓ 4 bookmaps without maps to create short, direct instruction –

bulletin: recall, upgrades, technical tips, part obsolescence

• 10 Word templates – 6 DITA templates➢Can reduce this once everyone learns the basics by introducing

conditionalization, variables, and others

Dilemma 1

#LavaCon

8 | VARIAN ONCOLOGY SYSTEMS

– train many content developers

Mimics current Word templates and process

Limits the very broad tools and simplifies the

required process

Reduces training to basics of template

requirements

✓Minimizes and directs initial training content

✓Both hands-on and written

✓ Includes basic instructions within <comment>s and

drives guidelines

✓Offers ability to later upgrade templates with more

features such as conditionalizing and customizations

Dilemma 2

9 | VARIAN ONCOLOGY SYSTEMS

– QA with limited resources

Templates provide features that limit the QA

requirements and simplify troubleshooting

✓Structure within the broad open toolkit

✓Adherence to the information model

✓Synchronization with transformation design

✓Examples of correct element and attribute usage

✓Control of reuse topics with common information

✓ Implementation of schematron is simplified

If necessary, a small team can collect and enter metadata

and/or insert maps or topics created by content developers.

Dilemma 3

#LavaCon

10 | VARIAN ONCOLOGY SYSTEMS

Manuals

Includes multiple, often lengthy, processes with

instructions or steps which are not necessarily

linear.

• Document structure

• Long and partitioned

• Template structure

• Bookmap with maps nested within chapters

• Specifies required metadata

• Includes reuse maps with specific document type common

information

• Contains brief instruction and examples#LavaCon

11 | VARIAN ONCOLOGY SYSTEMS

Bulletins – Recall Documents

Includes single process with instructions or steps

which should be followed in order.

• Document structure

• Short and direct

• Template structure

• Bookmap with topics nested within one part

• Specifies required metadata, including bookmap attributes

• Includes reuse topics with specific document type common

information

• Includes <topicref>s, <navtitle>s and instructions for topic

templates

• Contains brief instruction and examples#LavaCon

12 | VARIAN ONCOLOGY SYSTEMS

Manual Template Example<bookmap id="clo1409763298506" outputclass="normal" xml:lang="en-us">

<booktitle> <mainbooktitle>IPA Template</mainbooktitle> *<bookmeta> has been removed

<booktitlealt>Installation Product Acceptance</booktitlealt></booktitle>

<frontmatter><notices href="clo1409763296166.xml“ toc="no"/> <booklists> <toc/> </booklists>

</frontmatter>

<chapter><topicmeta><navtitle>IPA Introduction</navtitle> </topicmeta>

<mapref href="clo1409763196549.ditamap"/> </chapter>

<!--The following <chapter> is a placeholder. Add more as needed.-->

<chapter> <topicmeta><navtitle>Enter chapter title here</navtitle> </topicmeta>

<mapref> <!--Click on this <mapref> and enter the map id into the href in the attributes.> </mapref>

</chapter>

<chapter> <topicmeta><navtitle>Customer Technical Bulletin (CTB) Access</navtitle></topicmeta>

<mapref href="clo1409763297773.ditamap"/> </chapter>

<!--The following <appendix> is a placeholder. Delete or add more as needed.-->

<appendix> <topicmeta> <navtitle>Enter appendix title here</navtitle> </topicmeta>

<mapref ><!--Click on this <mapref> and enter the map id into the href in the attributes.>

</mapref> </appendix>

</bookmap>

13 | VARIAN ONCOLOGY SYSTEMS

Bulletin Template Example<bookmap id="clo1413238435901" type="CTB" xml:lang="en-us">

<booktitle> <mainbooktitle>CTB Template</mainbooktitle></booktitle> *<bookmeta> has been removed

<part>

<!--Create a topic using the Customer Information template and save it as Customer Info CTB-XX-YYY. Select the

following topicref and insert the ID of your new topic into the href in the attributes.-->

<topicref navtitle="Customer Information"/>

<!--The following topic is the general information topic which is in every CTB.-->

<topicref href="clo1413238431283.xml" navtitle="General Information"/>

<!--The following is the convention topic which is in every CTB.-->

<topicref href="clo1413238434044.xml"/>

<!--The following <topicref> is a placeholder for the topics which are your specific document. Add <topicref>s as

needed.-->

<topicref><!--Click on this <topicref> and enter the topic ID into the href in the attributes.--></topicref>

<!--The following is the customer documentation topic which is in every CTB.-->

<topicref href="clo1413238435183.xml"/>

<!--Create a topic using the Bill of Materials template and save it as BOM CTB-XX-YYY. Select the following topicref

and insert the ID of your new topic into the href in the attributes.-->

<topicref navtitle="Bill of Materials"/>

<!--Create a topic using the Revision Information template and save it as Rev Info CTB-XX-YYY. Select the

following topicref and insert the ID of your new topic into the href in the attributes.-->

<topicref navtitle="Revision Information"/>

</part></bookmap>

14 | VARIAN ONCOLOGY SYSTEMS

PSE Bookmap Templates

Manual Template

Product Acceptance Template

Customer Technical Bulletin Template

Recall Service Technical Bulletin Template

General Service Technical Bulletin Template

Technical Tip Template

#LavaCon

15 | VARIAN ONCOLOGY SYSTEMS

Create Bookmap Templates

How to do it• Use general bookmap

• Design internal structure

• You could make map templates

• Use comments for information and instruction

• (We use oXygen but DITA map and then attributes

shows as well.)

• Include or remove metadata as needed

• Include reuse maps or topics as needed

• The templates still allow for updating these topics in

one place and it will affect all documents

16 | VARIAN ONCOLOGY SYSTEMS

PSE Topic Templates

Customer Information

Service Rep Information

Technical Information

Bill of Materials

Revision Information

Product Acceptance Tasks#LavaCon

17 | VARIAN ONCOLOGY SYSTEMS

Create Topic Templates

How to do it

• Use various general topic types – concept

reference, and task as needed.

• Use sections, tables, definition lists, and others as

needed

• Use comments for information and instructions

• Include options to delete what is there or add more

as needed

#LavaCon

18 | VARIAN ONCOLOGY SYSTEMS

Topic Template Example

<reference id="clo1413582155714" xml:lang="en-us">

<title>Customer Information</title><refbody>

<section id="section_N1001D_N1001A_N10001">

<!--Enter your document specific information in the empty cell after the appropriate filled cell.>

<table frame="all" id="table_udj_lnm_h4" outputclass="Job_detail"> * table details have been

removed

<tbody><row>

<entry outputclass="colsep_none">Complaint Number</entry><entry />

<entry outputclass="colsep_none">Drawing Number.</entry><entry />

<entry outputclass="colsep_none">Estimated Hours</entry><entry />

<entry outputclass="colsep_none">File Name</entry><entry />

<entry outputclass="colsep_none">Revision Letter.</entry><entry

/></row></tbody></table></section>

<section id="section_N100A0_N1001A_N10001" >

<!--Enter your document specific information in the following <dd> elements. -->

<dl outputclass="purpose"><dlentry ><dt >Purpose</dt><dd >Enter your information

here.</dd></dlentry>

19 | VARIAN ONCOLOGY SYSTEMS

Topic Template Example Continued

<dlentry><dt>Modification Overview</dt><dd>Enter your information here.</dd></dlentry>

<dlentry><dt>Prerequisites</dt><dd>Enter your information here.</dd></dlentry>

<dlentry><dt>Products Affected</dt><dd>Enter your information here.</dd></dlentry>

<dlentry><dt>Reference Documents</dt><dd >Enter your information

here.</dd></dlentry>

<dlentry><dt>Required Tools</dt><dd>Enter your information

here.</dd></dlentry></dl></section>

<section id="section_N10105_N1001A_N10001">

<!--Enter your document specific information. Add or delete rows as needed.-->

<table frame="all" id="table_ssy_jhy_z4" outputclass="order"> * table details have been

removed

<thead><row><entry>Order No.</entry><entry>Description</entry></row></thead>

<tbody><row><entry/><entry/></row>

<row><entry/><entry/></row>

<row><entry>Order

from</entry><entry>888.VARIAN5</entry></row></tbody></table></section></refbody>

</reference>

20 | VARIAN ONCOLOGY SYSTEMS

Template Details

Tool set – Ixiasoft CCMS and oXygen editor

• Easy to create – just like a topic

• Placed in the repository’s system templates

• Create new topics – presented template options

Transformation

• Cover page details and/or header information

• Outputclass assignment

Instructions

• Bookmap and topic level – all include revision information

#LavaCon

21 | VARIAN ONCOLOGY SYSTEMS

In the Future

Once we fully implement DITA and most of our

users are familiar with the

basics, we implement

more features.

Possibly reduce the number of bookmap and topic templates.

Utilize conditionals, variables, and other features which are easier to introduce once people know

the basics.

22 | VARIAN ONCOLOGY SYSTEMS

Automated Conversion

❖Designed to fit into the templates with

minor adjustments

❖Provides DITA XML documents

❖As examples

❖For the content developers to update

❖Stilo Migrate

❖Includes manual clean up and preparation

❖Customized rules to match templates

#LavaCon

23 | VARIAN ONCOLOGY SYSTEMS

Questions – Now or Later

Catherine Long – catherine.long@varian.com

#LavaCon

24 | VARIAN ONCOLOGY SYSTEMS

Manual Template Demonstration

• Open the CMS and select manual template

• Show map creation options

• Show prepared bookmap

• map view

• Open in oXygen map view

• Scroll through to show:

• @type=IPA Metadata

• Reuse map

• Instructions within <comments>

• Show generated PDF

25 | VARIAN ONCOLOGY SYSTEMS

Bulletin Template Demonstration

• Open the CMS and select CTB template

• Show map creation options

• Show prepared bookmap

• map view

• Open in oXygen map view

• Scroll through to show:

• Metadata – bookmap @type=CTB

• Reuse topic

• Instructions within <comments>

• Show generated PDF