Automating Help BuildsUsing WebWorks AutoMap

1
Automating Help Builds Using WebWorks AutoMap

• Don TopazKronos Incorporated

2

• Our help system
• Dynamically merging help
• Planning for automation
• Pitfalls, Brick walls, and Close calls
• Lessons learned (maybe)

3
The Kronos Help System

4
(No Transcript)
5
Help features

• 15 Products, each with its own help volume
• Cross-references
• Popups 2 varieties
• Link from help to the application
• Supplemental customizable content for each help
  screen

6
Dynamically merging help

• Available with WebWorks help
• Can be any combination of help volumes
• Contents, Index, and Search are all integrated
• Merge can occur at any time, as long as
  individual volumes are mergeable
• Available only at help volume level

7
Merge Requirements

• All help volumes built with the same WebWorks
  Help template
• All help volumes include Output/wwhdata/info.txt
• /wwhelp folder and index.htm file are copied to
  the same level as help output folders

8
Our help outputs

• 15 products
• English help
• Plus Spanish and French
• Plus a 3rd-party reseller who needs special
  branding
• Plus 80 PDF manuals also produced as HTML output
• each for both Kronos the 3rd-party reseller

9
Source file features

• A single FrameMaker template for all docs (help,
  books, single-sourced)
• Use variables for products terms that change for
  Kronos/reseller and for book titles
• Global and local conditions
• Creative methods to allow inter-volume
  cross-references

10
The Challenge

11
Build process before automation

• Open the book file in FrameMaker
• Apply the appropriate variables and conditions
• Run AutoMap client
• Modify output folder name and title.js file
• Repeat for each help volume
• wpuba.exe helps, but only a little
• As product line grew, our building workload grew
  geometrically

12
Needs

• Build more help
• Build help consistently without manual error
• Log and identify build errors
• Avoid manual intervention

13
Planning challenges

• How long does it take to create something that
  you havent created before?
• Tell me what it is that you dont know
• Keeping the patient alive during the operation
• Do we do the job ourselves or seek outside help?

14
Planning decisions

• Choose a methodology that we could understand
• Recognize the difference between Ideal and Good
  Enough
• Identify clear and attainable milestones, with
  short distances between them
• Deal with toughest issues first, not last

15
The thorniest issue Accessing FrameMaker
programmatically

• Need to set conditions and variables before
  running AutoMap.
• Need to generate index with correct settings

16
What we knew and what we didnt

• The subjects in which we were expert-
  FrameMaker WebWorks- Putting together batch
  processes
• The subjects in which we were clueless-
  FrameScript- Any other mechanism to
  programmatically access FrameMaker

17
Options for the FrameMaker problem

• FrameScript
• Prostration and supplication before Engineering
  deities
• Use a semi-automatic process and declare victory
• Hunt for other solutions .

18
BuildFire

• BuildFire 2005 assists you in the production
  process by providing the means of pre-configuring
  output profiles that you maintain independently
  of the FrameMaker source files. Output profiles
  include
• Conditional text settings
• Variable definitions
• Help Script and XML definitions, including
  automatically triggering post-processing scripts

19
The Answer wpjob.exe

• wpjob, the other callable interface to AutoMap
• Uses a job file in XML format
• XML job file specifies variables, conditions,
  context (for context-sensitive help), top-level
  title, etc.
• Batch file specifies output folder name, location
  of log files, post-processing steps

20
How it works
21
Job file
22
Batch file
23
The good stuff

• It works!!!!!
• Easily searchable logs of all builds
• We can maintain it ourselves

24
The stumbling blocks

• Documentation for job files and wpjob
• Long variable list cant import a file
• Special characters
• WebWorks garbles my XML file!

25
Lessons

• Maximize elements that you know how to do,
  minimize elements that you dont
• Good Enough can be better than Ideal
• Test at each step, and keep a backup of anything
  important
• Accept WebWorks for what it is

26
Questions?