Much Ado About Templates: Reduce the Learning Curve and Increase Productivity at DITA Implementation with Catherine Long and Richard Perry

1 | VARIAN ONCOLOGY SYSTEMS

VARIANONCOLOGYSYSTEMS

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

CATHERINE LONGSENIOR TECH WRITER

SEPTEMBER 2015

RICHARD PERRYPSID MANAGER


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.


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


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.


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


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


– recreate various documentsMultiple 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


– train many content developersMimics current Word templates and processLimits the very broad tools and simplifies the required processReduces training to basics of template requirements

Minimizes and directs initial training contentBoth 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


– QA with limited resourcesTemplates provide features that limit the QA requirements and simplify troubleshooting

Structure within the broad open toolkitAdherence to the information modelSynchronization with transformation designExamples of correct element and attribute usageControl 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


ManualsIncludes 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


Bulletins – Recall DocumentsIncludes 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


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>  <chapter> <topicmeta><navtitle>Enter chapter title here</navtitle> </topicmeta> <mapref>  <appendix> <topicmeta> <navtitle>Enter appendix title here</navtitle> </topicmeta> <mapref > <topicref navtitle="Customer Information"/>  <topicref href="clo1413238431283.xml" navtitle="General Information"/>  <topicref href="clo1413238434044.xml"/>  <topicref></topicref>  <topicref href="clo1413238435183.xml"/>  <topicref navtitle="Bill of Materials"/>  <topicref navtitle="Revision Information"/> </part></bookmap>


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


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


PSE Topic Templates

Customer Information

Service Rep Information

Technical Information

Bill of Materials

Revision Information

Product Acceptance Tasks


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


Topic Template Example<reference id="clo1413582155714" xml:lang="en-us"><title>Customer Information</title><refbody><section id="section_N1001D_N1001A_N10001"><dl outputclass="purpose"><dlentry ><dt >Purpose</dt><dd >Enter your information here.</dd></dlentry>


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"><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>


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


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.


Automated Conversion

Designed to fit into the templates with minor adjustments

Provides DITA XML documentsAs examplesFor the content developers to update

Stilo MigrateIncludes manual clean up and preparationCustomized rules to match templates


Contact Information

Catherine Long – [email protected] Perry – [email protected]

mailto:[email protected]

mailto:[email protected]


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


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

Technology

Much Ado About Templates: Reduce the Learning Curve and Increase Productivity at DITA Implementation with Catherine Long and Richard Perry