1 / 8

Content Reuse at the Element Level

Content Reuse at the Element Level. Megan Bock Presented to the Silicon Valley DITA Interest Group. What is element reuse?. It is a strategy for designing your information to support long-term maintenance. It is not a macro for inserting something you would rather not type.

tempest
Download Presentation

Content Reuse at the Element Level

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Content Reuse at the Element Level Megan Bock Presented to the Silicon Valley DITA Interest Group

  2. What is element reuse? • It is a strategy for designing your information to support long-term maintenance. • It is not a macro for inserting something you would rather not type.

  3. Evaluating content for reuse • Content that you have to update regularly: • Titles and order numbers: infrequently used but subject to predictable change • Legal statements: directed, maintained, or reviewed by someone other than the writers who normally work on the deliverable • Content that is difficult to update: • Product or feature names: widely used and subject to unpredictable change • Technical terms: likely to be inconsistently used or having multiple meanings • Restrictions and steps: used in the same way in numerous places

  4. Element reuse candidates • Obvious candidates: • Product names • Installation paths • Icon references • Likely candidates: • Note elements (restrictions, prerequisites, tips) • Individual step elements • Not candidates: • Common nouns • Sentences

  5. Mechanics of element reuse • You can only reuse an element in the same context. • For semantically significant content, use the correct semantic element: filepath, varname, cmdname. • For non-semantic strings, choose the least restrictive element type: ph. • You should never use a content topic as the source for another content topic. • Include your reuse source topics in your main map (with toc, linking, print, search turned off)

  6. Sample elements • Syntax • Source:<element id=“element-ID”>content (including subordinate elements</element> • Reuse:<element conref=“source-file.dita#topic-ID/element-ID”></element> • Sample • Source:<ph id=“otk">DITA Open Toolkit</ph> • Reuse:<ph conref=“contentReuse.dita#conrefs/otk"></ph>

  7. Hazards of element reuse • A too-ambitious reuse plan can: • Endanger topic reuse outside your library. • Confuse new writers. • Complicate translation. • Reuse only works if it is used consistently.

  8. Element reuse for library maintenance • Legal boilerplate: Build publication-specific topics from one reuse source file • Production: Update all product and document order numbers (and other similar information) from one reuse source file • Accessibility: Reference all art from reuse source files with alt text and long description links • Retrievability: Define searchtitle element prefixes (example: V9 Administration - $topicTitle)

More Related