TC Camp Benefits for Managers

TC Camp is a vendor-neutral bay area event aimed at content designers, creators, publishers and the people who support them. There are morning workshops that cover specific tools like Adobe’s Technical Communications Suite, MadCap’s full publishing environment, or Aptara’s epub tools. There are also workshops aimed at specific documentation issues — content strategy, improving content through analytics methods, and improving content retrieval using library science concepts.

In the afternoon, there are open discussion sessions that are driven by the attendees. Anyone can suggest a topic for discussion: Is your team discussing XML? Are they looking at improving SME review cycles? Is localization on the horizon? Attendees can discuss topics that are staring us all in the face with other people who have conquered these issues.

We all have different levels of expertise as we face different issues and situations. At TC Camp we each extend our expertise to we can all learn from each other.

TC Camp is high-value, low-cost option for a training opportunity that provides access to industry experts like Scott Able, Sharon Burton, and Scott Prentice. It’s happening on a Saturday, so you’re not paying twice–first, you’re not paying for an employee who isn’t at work on a work-day, and you’re not paying the high cost of a typical conference.

What are the details?

When: Saturday, 26 January 2013
Where: Silicon Valley Cloud Center, 3200 Coronado Drive, Santa Clara, CA, 95054
URL: http://www.tccamp.org

All the content is guaranteed to be relevant to the attendees because, remember, they drive the discussion.

I hope to see your teams there. TC Camp will help your team grow in confidence because they’re learning from peers while contributing their expertise. They’ll be able to respond to your team’s growing needs and meet challenging new goals in the future.

LinkedInEmailShare

Comments off

January 9, 2013 · Filed under Conferences, events

A Fresh Look at FrameMaker (Version 11)

by Liz Fraley

I started supporting XML-oriented technical publications teams in the late 1990s. I’ve used nearly all the XML authoring tools out there, and I use several different ones on a regular basis every day for different purposes. Over the last month I’ve had the opportunity to spend some time with Adobe’s TCS4 and FrameMaker 11. I’m not new to FrameMaker. The first version I ever used was 5.5 back in the year 2000 and I’ve used a number of other versions over the years.

With this latest release, FrameMaker 11 has made the leap to being a true XML authoring application.

In the new UI, there’s an XML view with real-time validation, tree view and code view.  I’m a programmer by trade – a genuine computer scientist – so I come at publishing from the side of scripting, programming, and data structures. I want my XML pure and ASCII readable, and in FrameMaker 11, I’ve got it.

Whitespace handling is much better than previous versions as well. There’s also access to the document contents via XPath and XSL. Whitespace handling can be the bane of a tools-person’s existence when teams are using different XML editors causing havoc down the processing road, so to speak. It’s one of the things you need to be aware of if you’re going to let your team mix and match their tools.

I ran several tests with content created in one tool and then processed by the other. Standard DITA worked fine, even the keyref and conkeyref features of DITA 1.2.  Specializations – not as portable as I’d like, but if you’re doing Standard Dita (and you should – we tell people only to specialize when necessary), you’ve got a nice option in FrameMaker 11.

Elements can be inserted by pressing the Enter key, now a pretty common mechanism I’m glad to see. There’s also a nice smart copy/paste from Word and Excel. There’s a lot of multi-media support – mp4, swf, flv, and u3d, as well as hotspot support for 3d graphics.

DITA isn’t the only thing that’s built-in. There’s support for S1000D as long as you’re working with S1000D XML. I tried a bit of it out, but not as much as I might have. Support for the doctypes are there, but I couldn’t quite figure out how to get multiple version. Most of my customers are doing S1000D in SGML and not all of their projects use the same S1000D issue number.

Publishing has become really straight-forward for more than print output as well, as long as you’ve got the whole TCS4 suite. Publishing Server and RoboHelp support HTML5, EPub 3, Kindle, and Android Apps.  (I could test 3 out of 4 of these: I don’t have Android). But, perhaps one of the nicest enhancements is the extraction of publication settings to a settings (INI) file. For support teams, this is a serious win because it makes publication consistency easy to maintain for more than single-user teams.  And isn’t that part of the reason we all go to XML publishing?

In January, Single-Sourcing Solutions sponsored TC Camp. We had a morning class on the new features of Adobe’s FrameMaker 11 and I had my first view of it since version 9. I have to say that my eyes were giant saucers as I watched Max Hoffmann walk through the new features. Getting a chance to play with it was fantastic. There’s a trial version available for 30 days from Adobe’s site.  See for yourself: Download the trial.

LinkedInEmailShare

Comments (1)

May 6, 2013 · Filed under products

Arbortext Version 6.0 M080 Released

Here’s the list of SPRs and enhancements added to a product release. We highly recommend you log in to the support site and read the release notes (login required).

Here’s a short summary, but all Arbortext products have been affected in the 6.0 M80 release. Platform support, browser support, languages and localization are all addressed in the release notes.

SPR Fixes Summary

Most updates affect the following products:

  • Editor
  • Publishing Engine
  • Styler
  • ACL

See the list below to check if an SPR you’ve been waiting for is fixed:

  • Arbortext Editor Fixes
    • 2137590: Arbortext Editor no longer terminates unexpectedly when closing a document that contains an ISO graphic.
      2138591 Processing no longer fails for graphic entities declared in a parameter file entity that are passed to a cloned document.
    • 2151937: Highlighting of a text selection within a list, or at the beginning at an item, or within a block that has no previous block, persists as expected.
    • 2153284: Arbortext Editor no longer generates errors when inserting references to Dynamic Documents that have namespaced elements as the root element.
    • 2155534: Separate string tables for tags, attributes, default attributes, character entities, and choice lists have been implemented in Arbortext Editor. Arbortext Editor’s capacity to handle extensive quantities of these items in a document has been improved.
    • 2155727: Arbortext Editor no longer corrupts the doctype declaration in an XML topic referenced by XInclude and opened from a read only DITA map.
    • 2161118: Modifying non-standard attributes for an element no longer causes Arbortext Editor to terminate unexpectedly.
    • 2164844: Inserting markup into a document based on an XML schema no longer causes Arbortext Editor to terminate unexpectedly.
    • 2165936: Text shading configured in a stylesheet for a table cell is displayed correctly in Edit view.
    • 2166513: Inserting markup into a document based on an XML schema no longer causes Arbortext Editor to terminate unexpectedly.
    • 2167019: New ACL functions have been added to return the namespaces associated with certain elements:
      • bulleted_list_block_tag_name_ns
      • bulleted_list_item_tag_name_ns
      • numbered_list_block_tag_name_ns
      • numbered_list_item_tag_name_ns
      • text_style_tag_name_ns

      Refer to Miscellaneous ACL Changes in the Arbortext Editor, Publishing Engine, Styler, and Architect Release Notes for information.

    • 2167825: Fixes to schema_validate() , schema_validate_batch(), and validate_schema() functions ensure that error messages generated will be output to Arbortext Editor event logs as applicable.
    • 2170206: A table pasted into XML using the Edit->Paste Special->Table (from Tabular Text) menu option contains the correct number of columns colspec elements.
    • 2170668: Namespace prefixes are now set correctly on documents that are both displayed as an XInclude in a parent document and opened for edit in the same session.
    • 2172592: Modifying non-standard attributes for an element no longer causes Arbortext Editor to terminate unexpectedly.
    • 2173253: Highlighting of a text selection within a list, or at the beginning at an item, or within a block that has no previous block, persists as expected.
  • Publishing Fixes
    • 2070891: Conditions based on the value of the xml:lang attribute are matched as expected to provide generated text in the correct language.
    • 2094079: Scoped page numbering for a part generates the correct page numbers in all chapters when published to PDF via the APP engine.
    • 2120842: Images referenced from a Parts List display as expected when a PDF representation of the Parts List is published directly via Arbortext Publishing Engine.
    • 2122684: The index page number for a Table of Contents is correct in PDF output generated by the APP engine.
    • 2136540: Savetexts to pagedesc referenced variables in e-i-c’s of pseudo-tags in an index no longer cause Arbortext Editor to terminate unexpectedly.
    • 2151376: Composition errors are displayed as expected when performing a Format or Print Preview action using the FOSI engine.
    • 2155872: Tables that include rows that are entirely vertically spanned no longer display an invalid extra row when published to PDF output via the APP engine.
    • 2161729: Bookmarks generated from a TOC are ordered in the required hierarchy in PDF output generated by the APP engine.
    • 2164236: Numbering is output correctly for an element styled as a Formal Block when published to web output.
    • 2165949: The display of WMF images in PDF output generated by the APP engine has been improved.
    • 2166913: CMYK colors in an EPS file are rendered correctly in PDF output.
    • 2167473: Rules configured for the header row of a table with deepcontentsplitting applied are not duplicated in PDF output.
    • 2167477: Selected views of PVZ graphics appear as expected in PDF output.
    • 2167796: The FOSI string modifier [TB] outputs content as expected when working with Arbortext Styler and Arbortext Publishing Engine.
    • 2168026: The default table cell background color is white in HTML output generated by the Save as HTML action and the Publish->HTML file action when using a FOSI.
    • 2172906: Digital Media Publisher Help Center images are opened without error when accessing programmatically from a host product.
    • 2176014: Korean characters that are wider than a table cell no longer overflow the cell boundary in PDF output generated by the APP engine.
  • DITA Application Fixes
    • 2165271: Processing instruction wrappers for topic titles are ignored by DITA functionality when the topic is referenced in a DITA map.
    • 2168165: Arbortext now supports the abbreviated-form element.
    • 2170365: A source file that holds content that has been conref’d into an open document in Arbortext Editor can now be opened from the Resource Manager.
  • Arbortext Styler Fixes
    • 2162983: Link text in a cross reference from a nested step to another nested step now displays the correct number for the target step.
    • 2170202: Header row text configured for custom tables defined in a stylesheet module displays as expected in PDF output.
    • 2171131: The Previous level number dropdown menu no longer adds an additional / at the end of the previous level element when it is a ancestor of a title.
    • 2176574: An RTF Preview action is permitted in Arbortext Styler without the need for an Arbortext Import/Export license.
  • Arbortext Import Fixes
    • 2166765: An import to XML action captures alternate text for a graphic in an RTF file as expected.
  • Arbortext Publishing Engine Fixes
    • 2167132: An xref that is assigned the Link style in Arbortext Styler is fully functional in document output published to PDF with an http request to Arbortext Publishing Engine.
  • Arbortext Architect Fixes
    • 2163784: An SGML file that does not include a path to an SGML declaration file (.dcl) can still be compiled in Arbortext Architect, using a default file.
  • PTC Server connection and Repository Adapter Fixes
    • 2147565: Using the Update References action on a map will reflect changes to a referenced CMS object that were carried out independently of its parent map.
    • 2159572: A fragment comment in an Arbortext Editor entity file stored in Windchill is no longer lost when checking out the entity as a standalone object and editing in Arbortext Editor.
    • 2165924: Siteminder no longer prevents Arbortext Editor from connecting to Windchill 9.1 M060.
    • 2168159: A second request to connect Arbortext Editor to a different Windchill server, after closing the previous Arbortext Editor session and shutting down the Windchill server that provided the connection, no longer attempts to connect to the shut down server.
    • 2174900: Information Elements in a Publication Structure that were checked out with a single action are all checked back into the Windchill repository when using the Object ▶ Check In All Objects menu option.
  • XUI Fixes
    • 2168820: Custom XUI dialogs now refresh correctly when new controls are added.

For more information..

Documentation supporting Arbortext is delivered in the Arbortext Editor Help Center. Documentation for this and all recent releases can also be downloaded from the Reference Documentation area of  the PTC web site at support.ptc.com.

LinkedInEmailShare

Comments (1)

May 6, 2013 · Filed under release notes

Arbortext Version 6.0 M070 Released

Here’s the list of SPRs and enhancements added to the 6.0 M070 product release. We highly recommend you log in to the support site and read the release notes (login required). Here’s a short summary of SPRs that were fixed in this release, but platform support, browser support, languages and localization are all addressed in the release notes.

SPR Fixes Summary

  • Editor Fixes
    • 2137590 Closing a document that contains CGM graphics with a doc_close(current_doc())command no longer causes Arbortext Editor to terminate unexpectedly.
    • 2142622 Character entities in attribute values are converted correctly in an XML conversion with a write command.
    • 2147147 TIFF graphic support in Arbortext Editor has been upgraded. Graphics will now be corrected if necessary and displayed correctly in both Editor view and output.
    • 2150578 Arbortext Editor no longer terminates unexpectedly when processing or verifying an xref with an invalid href value.
    • 2150604 Empty elements in FOSI stylesheets no longer trigger warnings at startup.
    • 2151345 It is now possible to insert a list into an empty element with a protected region, for example from trailing generated text.
    • 2151410 A XUI dialog box field displays the expected background color when the value of its readonly attribute is changed.
    • 2153320 The default value of the deepcontentsplitting preference is on for documents based on the Technical Information Application.
    • 2153477 New instances of documents from supplied document types are created without error.
    • 2154440 The names of fonts that have rotated versions no longer appear in font lists presented by Arbortext Editor
    • 2156541 When viewing a read only document from a CMS repository via an Arbortext Editor Adapter, the option to update the document’s profiling values is no longer presented.
    • 2156844 Arbortext Editor no longer terminates unexpectedly when opening a document that contains certain character combinations in its text content.
    • 2157643 The mouse wheel will still scroll a document when the useepic43keymappings preference is set to on.
    • 2158209 The embedded dpi value of a PNG graphic will be used to assess the intended size of the graphic in published output.
    • 2159422 Arbortext Editor no longer tries to copy a _bookmark UDT definition from a child file referenced by XInclude. Closing the parent file will no longer issue a prompt to save changes.
    • 2163500 The Select button is now available when linking to .idr (IsoView) graphics in Arbortext Editor.
  • Publishing Fixes
    • 2069356 A link to a target containing a table functions correctly in PDF output.
    • 2133678 Profiling information from a custom DCF file is passed as expected to the PE server during a publishing action via Arbortext Publishing Engine.
    • 2144756 Link destinations resolved in hidden parts of a document published to PDF no longer contribute to the limit set for a single point.
    • 2149230 Arbortext Editor no longer occasionally stops responding when using the APP engine to publish documents containing single-column elements that are kept with a subsequent span.
    • 2151524 ISO graphics with hotspot links display correctly in PDF output generated by the APP engine.
    • 2151590 RTF output of a two tgroup table now displays the correct column headings in the second tgroup after a page break.
    • 2151636 Double quotes in XPath expressions in FOSI edited source no longer result in context errors in an exported FOSI stylesheet.
    • 2151792 When the FOSI composition engine configures line spacing for equation graphics, a negative vertical offset for the graphic will result in an equivalent amount of space being removed from the height of the graphic and added to the depth of the graphic. The equation will be spaced correctly with reference to following and preceding lines.
    • 2152951 ElementLabelandNumber settings for generated text in index terms are respected in PDF output generated by the APP engine.
    • 2153569 Graphics with transparent backgrounds are displayed correctly in PDF output generated by the APP engine.
    • 2155094 In PDF output generated by the APP engine, cross references to a paragraph that displays a page number include the page number in the link text when the cross reference originates in a footnote.
    • 2156417 A KEEP too large – content has overflowed error message will no longer be generated in error by the APP engine when content has been balanced but does not actually overflow the format area.
    • 2156709 Publishing a parts manual with the APP engine no longer results in JavaScript errors.
    • 2156788 A cross reference to an element without a title will no longer generate JavaScript errors warning that the element is undefined.
    • 2157101 Duplicate index entries from a document’s topics do not appear in the output PDF’s index when generated by FOSI engine.
    • 2157471 The APP engine will no longer report column too narrow errors when a line wraps, having fitted just a space.
    • 2158087 Items in footnotes that are configured to be hidden are suppressed as expected in PDF output generated by the APP engine.
    • 2158249 An update has been made to APP’s recovery of KEEP too large errors generated when a table is bigger than the page and every row must always keep with the previous row. The table will now flow off the bottom of the page instead of stopping the formatting of the document.
    • 2161547 APP will longer assess content that is too wide for a column in a table as too wide for every column in the table. Errors will be logged but formatting will continue as expected.
    • 2162858 A document with a stylesheet association defined with a relative path will no longer output a cannot find file stylesheet error message when it is published to PDF.
  • DITA Application Fixes
    • 2146737 Arbortext Editor via the IBM DM adapter no longer terminates unexpectedly when resolving an xref to an ID that ends with a . character.
    • 2154693 The consequence element in the Technical Information Application distribution now permits the entry of mixed content.
    • 2156877 A graphic appears as expected in a DITA document checked out and opened in Arbortext Editor via the Documentum adapter
    • 2157309 The value of the outputclass attribute set for a topic is no longer cascaded to any of its child topics, apart from between a topicref and the main topic or topics in a ditabase.
    • 2159373 An xmlns:atgra namespace declaration is no longer included in new xref and link instances.
    • 2160600 Inserting an xref using the Current Document button in Arbortext Editor’s Resource Manager to navigate for the target will insert an active same document cross reference as expected.
    • 2161131 The option dita::_setShowCMSCurDocPath manages the path information displayed in same document cross references inserted using the Current Document button in the Resource Manager:
      • 0 – name of current document only is displayed
      • 1 – name of current document plus folder path is displayed

      The default value is now 0.

  • Styler Fixes
    • 2150807 An update to the PStill installation has improved the handling of EPS graphics.
    • 2153662 Exported XLIFF files now include an id attribute on x elements. The file can now be validated by Arbortext Editor and translation applications
  • Import Fixes
    • 2146315 Alternative text elements for a graphic are captured in a Word-XML transformation into Arbortext Editor.
  • PTC Server Connection and Repository Adapter Fixes
    • 2149492 The approach of using the Windows Certificate Store via Internet Explorer to support two way SSL (client certificate) authentication of a connection to a Windchill server has been introduced in this release. If the existing client certificate is in an external file, or in a certificate store for a different browser, import it into to the My Certificates section of the Windows Certificate Store using the steps detailed below. The steps must be completed for every PC that will be used to access Windchill in this way.The Windchill server administrator should generate a certificate if one does not already exist.
      • In Internet Explorer, access the Tools->Internet Options menu option. Click the Content tab then the Certificates button.
      • In the Certificates dialog box, click Import.
      • In the Import dialog box, browse to the location of the client certificate file then click Next.
      • Type the client certificate password and ensure that the Enable strong private key protection check box is NOT checked.
      • Store the certificate in the Personal key store.
      • Click Finish.
      • Verify that Windchill can be accessed using Internet Explorer. If this is successful Arbortext Editor should be able to connect to Windchill using the imported certificate.

      Note: If the Windchill server requires smart card authentication, insert the card into the reader attached to your computer before attempting to connect Arbortext Editor to Windchill.

    • 2155353 Arbortext Editor’s list of valid characters for workspace names when working with the adapter to Windchill now matches the list in Windchill.
    • 2159196 Arbortext Editor no longer displays an error message when you elect to work offline in a newly created workspace.

For more information..

Documentation supporting Arbortext is delivered in the Arbortext Editor Help Center. Documentation for this and all recent releases can also be downloaded from the Reference Documentation area of  the PTC web site at support.ptc.com.

LinkedInEmailShare

Comments (1)

January 25, 2013 · Filed under release notes

Arbortext Advanced Print Publisher (APP) Version 11 M030 Released

APP Version 11.0 M030 is available for download on the support site.  Here’s the list of SPRs and enhancements added to the product release. We highly recommend you log in to the support site and read the release notes (login required).

SPR Fixes Summary

The release notes say this:

  • Fixed <?bkw> so it correctly adjusts the line width when stripping off a preceeding word and then works with <?tjl>. (SPR 2121163)
  • Fixed row start command from being ignored following an empty block at the top of a row that has just overflowed to a new page. (SPR 2133003)
  • Fixed regression with <?bk>…<?ek> when used in conjunction with <?tbchmode 1> to make a column as wide as it’s longest word. (SPR 2097304)
  • Updated font system to use fonts internal unitsPerEm. (SPR 2147087)
  • Fixed use of queues when they preceed a Javascript instruction to start a block or table. (SPR 2120194)
  • Fixed possible repeated characters when hyphenator fits whole word on line. (SPR 2111160, SPR 2135875, SPR 2144873)
  • Fixed hyphenation problem when formatting a call-in loop from a JavaScript function. (SPR 2111160)
  • Fixed crash when printing to PDF/A-1a without setting Generate Tagged PDF option. (SPR 2122114)
  • Fixed issue using fStyle.underline in the middle of a line (SPR 2153726)
  • Fixed JS ex_map template so the resulting 3d file can be reloaded correctly after being saved.
  • Fixed issue with try tables saving and restoring text properties correctly (SPR 2145691)
  • Added “xmlscope” parameter to XML indexes, allowing them to select index references based on a location path.
  • Prevented global search from inspecting JavaScript tags, causing crashes (SPR 2127005)
  • Fixed occasional crashes testing context matches (SPR 2129307)
  • Fixed crash when misusing FOM XPathException objects (SPR 2151969)
  • Fixed contexts to match comments and PIs when only using contextup (SPR 2154340)
  • Fixed problems where text nodes in SVG are no longer rendering and causing errors (SPR 2154178)
  • Fixed issue with FOM formatting.addImage when the image size evaluates to more than 3 decimal places.
  • Fixed issue when printing to Tagged PDF file for a second time, after a tformat. (SPR 2121676)
  • Improved error logging when printing to PDF. (SPR 2121676)
  • Fixed issue with heading maps not working when not sorting indexes (SPR 2145902)
  • Added 2 new Pantone+ Colour Books.

A note from the PM, Simon Taylor:”The big deal is SPR2147087. THIS FIX WILL MAKE MANY DOCUMENTS APPEAR DIFFERENT. Changing the internal font metrics for TrueType font handling means that when APP measures text to ensure it will fit on a line, it will now get different results, which may cause line endings to change. The new result is more accurate and therefore better, but please be aware of this change.”

The FOM release notes have this to say:

  • Added fLog.logMsg() method.
  • Added fApplication.jsDebugFlag property and fApplication.jsDebugFlags constant group.
  • Modified fStyle.variant type from int to string.
  • Added fTemplate.errorLogOverrides property.
  • Fixed documentation for fFormat.errorLogOverrides.
  • Added fTemplatePreferences.formatting property.
  • Added fTemplatePreferencesFormatting object.
  • Added fPDFLayer object.
  • Added fFrame.pdfLayer property.

A note from the PM, Simon Taylor: “Notice the addition of fPDFLayer and fFrame.pdfLayer properties. These are provided as a Technology Preview only at the moment – this means it is not yet complete and is not yet supported but we’d be happy to hear your feedback if you have a play with it. Using this you can create a PDF layer in your PDF output and put a frame on that PDF layer. The print dialogue has an option to create PDF layers. We expect to extend it further for the next major release.”

For more information..

Documentation supporting Arbortext is delivered in the Arbortext Editor Help Center. Documentation for this and all recent releases can also be downloaded from the Reference Documentation area of  the PTC web site at support.ptc.com.

LinkedInEmailShare

Comments off

January 22, 2013 · Filed under release notes

5 Tips for keeping your content flexible

One of the articles in our newsletter this month generated a great discussion with one of our customers.  I wanted to follow up here with their questions and some deeper information.

First: here’s the article from the newsletter:

Whether you’re translating or not, some practices can make it easier for you to future-proof your content.

Tip #1: Use numbers for your call-outs and have a legend table.

There are two benefits to this “old school” method. If you ever decide to convert your content, there won’t be an additional work (or charge) to recreate the call-out content in the new tool. It’s rare for two tools to use the same mechanism for drawing features, so it rarely converts cleanly. Second, not all languages fit in the same space, or even go the same direction (right-to-left vs left-to-right). Call-outs will need to be re-sized or moved entirely in a graphic that gets put into a translated document. Both of these mean more work (and more cost) for you at the time the translation happens as well as every time the document is updated. Simply put, use numbers — not text — in your call-outs.ß

Tip #2: Put the call-outs in the graphic itself.

This is a corollary to tip #1. Use the same tool that creates the graphic to insert the call outs so they’re part of the graphic and not an in-between layer. Going to a mobile format? Going to the web? Both of these import graphics by reference. If the call-outs are in the graphic, you get them automatically in the other formats.

Tip #3: Don’t use variables in text for sentence fragments.

Sentence fragments have ripple effects when it comes to translation. First, not all languages have the same sentence structure. Phrases may not be isolated the same way in another language. Variables should be reserved for items that are not affected by translation like graphics, proper names, numbers, or other truly one-for-one substitutable textual items. Before you use a variable, make sure they pass the isolation litmus test.

Tip #4: Don’t nest your topics. (DITA)

Nested topics cause problems for translation houses. Flattened structures can improve the processing because they create a linear-ordering for word experts. This is particularly important when going to Asian languages. Topics need to be fully enumerated before they can be evaluated. Nesting impedes the process and complicates the analysis before translation is completed. With nested topics, the structure is hidden from the translators. It’s generally a better practice to use a sub-mapping structure rather than nesting.

Tip #5: Don’t use tables for procedures.

First, conversion is complicated for for these kinds of structure. Automated conversion can’t tell a procedure from tabular data when a procedure is embedded in a table structure. Second, when you use a table for a procedure, you have to manually maintain the numbering as you insert or delete steps. That’s a difficult situation to maintain, especially as the procedure grows and spans pages. Use structures that support numbered steps when that’s what you’re creating.

Most of the questions had to do with Tip #4 and the notion of what I meant by “flattening” and “nested“.

When I talk about “nested” topics, I mean topics that exist completely inside other topics. That is, the entire topic appears between the open and close tags of another topic. A nested topic looks like the structure below:

nesting-topics

In this case, there is a complete concept inside another topic. That’s a nested topic. And, when I say it’s better to flatten, I mean to pull that concept out of the parent topic and make it a topic on it’s own. Typically, nesting is used to simulate hierarchical structure. But with DITA, there are other ways to construct hierarchical structure. You can add structure with a map:

nesting-and-maps

The topics in the red box in this map show three levels of hierarchical structure — what is essentially three levels of heading (head 1, head 2, and head 3) — without nesting the topics.

And just a note about Tip #2: Remember Tip #1. Or, as one reader put it:

“If there is any chance that your docs will be translated, do not embed text (words) in the graphics.  It will cost you $25 to $50 per graphic, per language, to have the LSP (localiztion service provider) open each graphic, translate the text, save the graphic, and replace the file in your authoring tool or CMS.

Cost saver tip: Before translating your docs, replace all text in graphics with numbers and use a legend table below the graphic as described in Tip #1.

Usability tip:  if possible, keep the legend table on the same page as the graphic.”

LinkedInEmailShare

Comments off

January 10, 2013 · Filed under common questions

« Older Posts