Documentation Legos


  • About Me
  • Why DITA?
  • Reusing chunks
  • Augmenting your reuse
  • Standard
  • Building on a foundation
  • Why not?

About me

Zoë Lawson

Technical Writer for 15+ years

Working with DITA for 10+ years

Helped trailblaze Quadralay ePublisher's DITA Adapter

Script monkey who enjoys making chewing gum and bailing wire


Small topics are building blocks to reuse

Many, many features to enable more reuse

Open source standard that can "easily" be used elsewhere


Building blocks

  • Easily mix and match topics in ditamaps

    A "bookmap" (PDF) and a "map" for HTML/Help output

  • Easily have shared/common topics

    Legal notices, contacting support, etc.

  • Small chunks that can be translated in small chunks

  • Smaller blocks possible to reuse specific paragraphs, words, chunks of content

    @conref is your friend

Modifying blocks

  • <titlealts>

    You can change the title of your topic via the ditamap, have one title in the topic, and a different in the table of contents, and a still different one in search results.

    For example, shorter title in the TOC, but make sure you include the product name in search results

  • With keys, you can easily change references in the same content based on ditamap

    Super useful for product names, especially for different components with a shared installation guide

    For image references, can have high res for PDF and lower res for web

  • With conref push, you can insert information into topics

  • With ditaval, you can filter your output and have conditional text

Open standard

  • Technically, you can use DITA for free

    This presentation was generated using the DITA-OT, Reveal.js from GitHub, and Notepad++

  • Technically, if you author in DITA, anyone else can use your source to produce output

    Exactly the same way all browsers render the HTML standard the same way

    The above line should be in the sarcasm font...

  • As more and more people adopt DITA, there are more and more tools that make it more accessible

    You don't have to be an XML, XSLT, JS, JAVA, ANT, and DITA expert to use it with oXygen Author, FrameMaker, etc.


  • If you want to get fancy, you can create specializations

    The task, concept, and reference topics are all specializations of the generic topic type

  • You can transform DITA into anything

    All you need is the code to support it

    The transformation into Reveal.js is an extension. I've seen people make animations/videos from DITA source, ways to transform the content to flavors of wiki formats, messages to be used in UIs

  • More tools are supporting DITA

    I've found plugins to pull DITA content into WordPress

Why Not

  • DITA is very rich and featured

    DITA can do all the things...if you have the people or tools to make it work

    If you are a sole writer, probably not the best choice unless you are technically saavy.

  • Beware of DITA Tools that 'augment' your DITA

    Many companies offer Content Management Systems that help create index term libraries, conrefs, etc. These may be proprietary formats that are no longer sharable.

  • Just becaused you can doesn't mean you should

    There's probably at least 3 ways you can do the thing you want to do in DITA. All of them will work, some will work better than others, some will provide more gray hairs than others.