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
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.
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
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.
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
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 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
8 | VARIAN ONCOLOGY SYSTEMS
– 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
9 | VARIAN ONCOLOGY SYSTEMS
– 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
10 | VARIAN ONCOLOGY SYSTEMS
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
11 | VARIAN ONCOLOGY SYSTEMS
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
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
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
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
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
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 documentsAs examplesFor the content developers to update
Stilo MigrateIncludes manual clean up and preparationCustomized rules to match templates
23 | VARIAN ONCOLOGY SYSTEMS
Contact Information
Catherine Long – [email protected] Perry – [email protected]
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