Meeting: Round table discussion – importing DITA into InDesign

We had an interesting discussion dealing with how to best import DITA files into InDesign (specifically CS4 and CS5). It was a very hands-on meeting, with a real-world project as the test bed.

Like most DITA-type projects the important thing is the preparation. Importing the actual DITA files is as simple as File > Import XML, and then dragging and dropping elements onto the artboard.

Create Paragraph tags to match your DITA tags and use Structure’s Map Tags to Styles to create a table that brings in the formatting easily. To modify the text, just edit the paragraph style.

When adding multiple DITA files, use Append when adding to an existing flow (good for columnar text) and use Merge when creating a new flow (good for individual text boxes).

Notes provided by Joanne Grey

Start Thinking Like a CCO (Notes)

The November meeting of SVDIG was held Wednesday November 10 at 7:00pm at Dell KACE, 1981 Landings Drive, Mountain View, CA. Presenting were Cynthia Canino and Tim Bombosch of Astoria Software (a Windows-based, object-oriented content repository). Approximately 25 people attended.

The talk was very interactive, with many audience members asking questions and participating in the discussion, especially to debate the appropriate metrics of the ROI calculator.

Cynthia and Tim began by stating that the title of “Chief Content Officer (CCO)” is a common title in the broadcast industry (in which “content” has high acknowledged value) but is rare in high technology. They suggested that content should (or DOES) have higher value in the technological realm, and that exploring and surfacing the value is in the best interest of both users and content producers.

According to Cynthia and Tim, some of the important values that drive CCOs are efficiency, branding, quality, compliance, and revenue.

The last part of the meeting consisted of a run-through of a spreadsheet set up to calculate ROI resulting from a typical move from unstructured (and unmanaged) content to structured (and well managed).

-Anna van Raaphorst

Meeting: Start Thinking Like a CCO (Chief Content Officer): Understanding the Corporate Value of Content Management

Cynthia Canino and Tim Bombosch of Astoria Software presented this thought provoking session on treating your content more like a corporate asset.

Think_Like_a_CCO.pdf

Meeting Notes

Pics from DJ Cline

Meeting: Writing Effective Task Topics in DITA

Another great presentation by Michelle Carey and Shannon Rouiller (Technical Editors and Architects at IBM)! They covered the fundamentals of creating a DITA task topic as well as some of the more controversial and confusing issues that writers run into when creating tasks.

DITATaskTopics_090310SR.ppt

Notes from Tom Idleman (Thanks Tom!)

  • Combine small tasks, such as “Click OK”, with more significant tasks in one step.
  • Beware procedures that simply list imperative steps to interact with the UI without setting context or talking about why the user is performing the steps: “1. Click A. 2. Click B. 3. Click C…”
  • 9 steps, maximum, per task topic.
  • Only describe one way to do something.
  • Tag optional steps with the attribute importance set to optional.
    Note that IBM output generates an “Optional” label for steps tagged with importance = optional. (The label is not generated with a pre DITA-OT 1.5 PDF processor, a known issue with previous versions of the standard PDF processor.)
  • Instead of tagging something like “The blah window opens” as a <stepresult> of a step, use the information to set the context of the following step: “In the blah window, do thus and so.”
  • Use <choices> when a user has several choices in a step that can be explained in a short phrase. Use <choicetable> when a user has a combination of options, such as “In Windows, do this. In Linux, do that.”
  • IBM uses standard headings in task topics for the various parts of the task topic as follows:
    • Before you begin (Prerequisite)
    • About this task (Context)
    • Procedure (Steps)
    • Example (Example)
      Or if a <title> element is used in the tag, the text Example is overridden by the text of the <title>
    • Results (Result)
    • What to do next (Postrequisite)
  • IBM uses inline icons: “Click the (graphic of icon) icon.”
  • IBM uses gerunds to start task topic titles: “Medicating Your Cat”
  • IBM tags command names with <cmdname> when talking about the command and <userinput> when the user has to type the command name at a command line.
  • To construct a supertask, or in other words, a task that consists of many subtasks, IBM uses the following strategy in a DITA map:
    • A concept topic <topicref> that points to a concept that talks about the overall supertask.
    • An attribute setting of collection = sequence for the concept topic <topicref>
    • Embedded <topicref>s that point to the tasks that make up the supertask within the concept topic <topicref>.
    • The result is a concept topic with numbered links to the tasks that make up the supertask that looks like the following:
      “Emergency Diving a Submarine
      When your boat is spotted, submerging quickly is essential. The emergency-dive process is both complex and unforgiving. The individual tasks must be performed in the proper order and in a timely manner:

      1. 1) Clearing the Bridge
        The first step of an emergency dive is to get all personnel off the bridge of the submarine and safely into the boat. Typically, the OOD (Officer of the Deck) yells “Clear the Bridge” and sounds two bells to signify an imminent dive.
      2. 2) Closing the Hatches
        Before a submarine can dive, all external hatches need to be closed. Typically, only the conning tower hatch will be open, but more might be open depending on recent activity on the boat.
      3. 3) Stopping the Engines
        Submarine diesel engines require air intake to function. To prevent possible damage to the engines, stop them before closing the main induction.
        …”
  • To set prerequisite tasks, IBM sets the importance attribute to required for prerequisite tasks. This automatically creates a link in the prerequisite section of subsequent sibling task topics to the topic that’s topicref is set to importance = required.
    Note that this doesn’t work for our standard output. It’s currently unknown whether our changes to the OOB OTK functionality is short circuiting this behavior or if IBM has added this to their output.

Release 6.0 of DITAinformationcenter (a free DITA resource)

Release 6 of DITAinformationcenter was published today.

This version of our free DITA information and modeling resource supports DITA Open Toolkit 1.5.1 (final build) and the DITA 1.2 language standard (still to be approved).

New features include:

  • We have eliminated the code distribution. We recommend that you install the DITA Open Toolkit instead.
  • We have added topics on how we automated the creation of DITA files to document WSDLs (web services) using a Python script.
  • We have added topics on using Python code to do machine translation using Google Translate and Microsoft Translator (Bing).
  • We have added information on using Simplified English to improve the quality of translated content.
  • We are providing sample translations in Spanish and German of the garage and grocery shopping samples done using Google Translate and Microsoft Translator.

You can download the DITAinformationcenter from either vrcommunications.com resources page or xmldocs.info, which has been converted to a WordPress site.

-Anna and Dick

Meeting: Round table discussions — conversions, output, and authoring

We had a very lively and energetic discussion of various topics. I’ve organized them into three main groups below.

TOPIC 1: Converting unstructured content into DITA

Before conversion:

  • Perform document analysis; better to spend more time on this than not enough
  • FM – look into using the Remove All Overrides command to clean up files
  • Prototype project should not be the first book you want to convert. This should contain bits that represent all possible structures and components in your documentation set. Test and perfect the conversion, then test and prototype the various output options you plan to use.

Conversion processes/tips:

  • Use Mif2Go convert to DITA – export to Mif, then set up mif2Go config file to set up elements, wrapping syntax for Mif2Go, etc.
  • Use FM Conversion table to map styles to elements, wrap elements into other elements, etc.
  • Create a base topic for each section (Parse on Heading 2 or Chapter) to get files into DITA
  • Conditional text boundaries need to map to to element boundaries. This is applied as attributes on those elements. It’s often better to rewrite heavily conditionalized content into multiple paragraphs so you can apply conditions at the paragraph level.
  • Frame’s conversion tables don’t map conditions. Any tools that do?
  • Variables can become conrefs or just make them into plain text.
  • Remove inline cross-refs and create relationship tables.
  • The DITA 1.1 bookmap provides nodes for book-like structures like chapters, appendixes, and lists (TOC, index, etc.).
  • If using Frame for PDF output, your TOC and index can be FM generated, otherwise they are generated by the tool (OT, or ?).
  • If in doubt, shred your content to be more granular. It’s easier to merge multiple topics together than break them apart later. Don’t use “sections” if you can help it, they can probably be topics.

Best practices?

  1. Think about why you want to convert – based on current content, maybe only convert tasks, or other topics that are truly concepts or reference.
  2. How much material – manual or automated conversion
  3. How often you will convert – 1 time, or often
  4. Source material is in-house or external, both?
  5. How well or poorly structured
  6. Do a good doc analysis – go through doc set and see how well formed they are try to capture all use cases, what is in the docs? What do the styles mean?
  7. Too few or too many steps in conversion process – a step may have too much transformation , try small steps with iontermediate results to try out
  8. Prepare documents for DITA (to be good DITA) before conversion.

TOPIC 2: Options for generating output from DITA

  • The OT provides scripts for generating, CHM, HTML, Eclipse Help, Java Help, PDF, and more.
  • Basic output is not too hard, but styling/formatting can be very difficult for non-techie people.
  • Suite Solutions offers great training for the OT if you want to learn how to maintain things yourself.
  • CSS can be a simple way to customize OT output.

Options other than the OT:

  • DITA2Go can be a replacement for the OT; from makers of Mif2Go
  • RoboHelp
  • Flare
  • XMetaL comes with OT bundled so it may be easier
  • CHM to Web – generate HTML HELP from the OT and then use a template to convert to WebHelp
  • FrameMaker can be the easiest way to generate PDFs from DITA even if you’re not using FM for authoring.
  • DITA-FMx provides extended PDF/book publishing features.

TOPIC 3: Authoring tips and ideas

  • Author Assistant from SDL – Grammar Checker requires tweaking (free download for FrameMaker 9)
  • Capture “what do I do now” moments – what do you do when something does not fit the model. Good to review later and share with others.
  • See Megan’s SVDIG presentation on creating Supertasks (tasks with links to subtasks)
  • Indexterms in prolog, become meta keywords; this is good for HTML. Indexterms inline are good for PDF/print. Decide which is more important. Once you move indexterms into prolog it’s hard to get them back inline; investigate tweaking XSL to copy inline indexterms to prolog for both purposes.
  • DITA-FMx and Oxygen provide element sensitive online Help for DITA documents. Makes it easy to learn how things fit together.

» Thanks to Lauren Katzive for taking notes!

Meeting: DITA without a CMS, Ben Colborn (Citrix)

Business: Remote access and virtualization, infrastructure products

Organization: Training (also Technical Publications)

Objectives: Temporarily add to functionality of XMetaL and the DITA Open Toolkit, eventually purchase a CMS to handle the same tasks (they have since moved to DocZone)

Requirements, Issues: Automate edit/review of training material, translate into multiple languages, PPT a required target, SCORM package required, search and link management issues

Key Tools: XMetaL, svn, custom tools produced in-house by Ben and others

Sample Custom Solutions: Excel/VBA macros, script to create stub topics to get writers started, search facility using JEdit, script to build SCORM package, semi-automatic transformation to PPT from DITA source

Sample Challenges: Customizing PDF output, multi-volume books, SCORM requirements, instructor requirement to use PPT

Possible Future Challenges or Barriers to Reuse: Training and publications departments are now using different CMSs (DocZone on Alfresco and Astoria)

Conclusions: You don’t need $1 million in tools to achieve some of the key CMS functionality required/useful in a DITA environment. What you learn doing custom tool production will help you choose the right commercial CMS when that opportunity presents itself.

Free Resource: Fifth Edition of DITAinformationcenter (DITA 1.2, Toolkit 1.5.1)

Hi, All —
Dick Johnson and I have just released the fifth edition (publishing date June 30, 2010) of our DITAinformationcenter code distribution, documentation, and DITA project sample source files, available at:
www.vrcommunications.com/resources.htm

or
www.xmldocs.info
This release focuses on DITA 1.2 features and DITA Open Toolkit 1.5.1 (final build).
The code distribution contains:
– DITA Open Toolkit 1.5.1 (final build)
– PHP interpreter 5.1.4
– A number of PHP debugging and reporting tools (also available in prior editions)
– A new Python repair tool (DITArepair) that fixes bad references (for example, if files have been moved and links broken) and also serves as an example of how Python can be used effectively in the XML/DITA environment
The documentation contains several DITA 1.2 features:
– Extensions to conref, conaction pushreplace: A Python script run in a preprocessing step to put keywords into shortdescriptions, both keywords present in the topic itself and also those keywords “inherited” from container topics
– Keyref: The values for publisher, copyright, and vrm version now have a single definition in a resource topics (instead of being defined separately in each topic)
– Coderef element: We have replaced some of the inline code examples with coderef elements that point to items in a code directory
Information describing how we implemented the 1.2 features are described in one of the topics (published as an appendix in the PDF output target).
Other documentation features:
– Added a section on trends in global communication and why DITA helps to solve some of the current challenges
– Information about our recommended DITAworkflow methodology based on the agile software development process
– New localization and translation topics and core vocabulary items
Sample DITA projects:
– As before, our grocery shopping and garage samples (garage is an expension of the garage sample available with the Toolkit)
– The current DITAinformationcenter source files, possibly useful as a model project of moderate size (350 topics) and complexity, and for testing processing tools. It contains a wide variety of DITA features, both from 1.2 and prior standards.
As always, comments are welcome. We hope the resource is useful to members of the DITA community.
-Anna and Dick

Meeting: WebHelp, Eric Armstrong

Who?
Eric Armstrong, Treelight Enterprises
eric at treelight dot com

When? Where?
June 9, 2010 at NetApp

What?
Context-sensitive WebHelp using a “preview feature” in XMetaL

Why?
No user download required

How?
Uses Javascript, XMetaL target (beta code)
Some customization required

Features (Pros)
Collapsible TOC
Index, search, browse
Print (but only single topic)

Cons
Does not launch if WebHelp already open
Links work (go to appropriate page), but framework not operational
XMetaL IDs are long and complex; Eric created his own unique IDs

For More Information

Tutorial by Su-Laine Yeo of JustSystems: http://forums.xmetal.com

Presentation: http://www.treelight.com/dita/CS_WebHelp.ppt

The demo page, to launch the CS help: http://www.treelight.com/dita/cs_webhelp/