Getting Started with DITA

Version 1
    Share This:

    A brief overview for a couple of  fellow Austin writers who have asked me recently how and where to get started  with DITA.

    I have gotten two similar questions about getting started with DITA in the  time span of about two weeks, so I thought I’d borrow from some of my answers as  a write-up for a blog post. One person wants to ditch her Adobe toolset in  frustration and try out some DITA workflows with all free tools. The other is a  lone writer in a small shop and wants to find out more about DITA and see if it  might work well in her Agile development environment.

     

    While I'm a huge DITA  advocate and see many ways that DITA can help with many doc goals, I don’t think  that DITA has all the answers necessarily. Topic-based authoring with just  concept, task, and reference types is a different mind set for both writing and  publishing. But, you could certainly put together a toolkit of freebies with  DITA to try it on for size. So here are some starting points.

    Get very familiar with topic-oriented writing

    Without some up-front information architecture and design where you really  analyze your documentation needs, and figure out what task, concept, and  reference means for your body of work, DITA won’t help you. Transforming legacy  information into topics may or may not be a worthwhile effort so some up front  analysis will help you.

    Bare minimum tool set to “do” DITA

    You’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728.  Here are direct links for the 1.3 package that you just download and unpackage  on your hard drive. Windows zip Linux tarball

     

    These full packages of the DITA Open Toolkit contain all the sub-tools that  you need for full evaluation from authoring to building output. Most of these  tools require the Java Platform, so, Java is a prerequisite to using the DITA  Open Toolkit. Download and install the Java Platform Standard Edition (SE) 5.0,  available at http://java.sun.com/j2se/index.jsp.

     

    Ant 1.6.5 runs automatic builds on your DITA maps, and the DITA Open  Toolkit gives you ant scripts for builds already.
    Xalan-J 2.6 is an  XSLT processor which is required to run the transforms.


    FOP 0.20.5 is  needed for PDF output. (Note: For compiled HTML help (CHM) you’ll need the HTML  Help Workshop, which isn’t included in the Open toolkit, but most help authors  will already have this installed.)

    ICU4J 3.3.4 is included for  improved NLS-enabled index sorting.
    Apache Catalog Resolver 1.1 is a  standard XML catalog mechanism.

     

    Plus, the newest full package (1.3) contains a startcmd batch file in  the root folder that you can use to set up your environment each time you run  the DITA Open Toolkit. Considering what headaches I had just with environment variables in Windows, I am  greatly appreciative of this little batch file.

     

    If you want to first just look at topics and create some output before  authoring anything of your own, look at the EvaluateOT.html file in the  root directory of your DITA Open Toolkit install. Double-click the startcmd.bat  file, then type ant samples.web -f build_demo.xml at the command line and  you will have your first set of DITA output in a newly-created \out folder in  your DITA Open Toolkit installation folder.

    When you want to create your own topics and maps, you’ll need an XML editor.  While you can certainly edit DITA XML in Notepad, you’re going to want a  validating XML editor for serious authoring and evaluation. See my suggestions  next.

    DITA XML Editors

    Previously I posted my notes from Don Day’s talk at the Central Texas DITA  User’s Group about evaluating DITA editors: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-editor-eval.  Now, the next step for me is to start naming names. Let me be clear, though,  since I’ve been on maternity leave for the last six months or so, I haven’t been  seriously evaluating XML editors for BMC. Others are doing that and I’ll be  happy to use whatever they recommend for our environment. But, for my friends  who have been asking me about DITA, let’s break this evaluation into free and  not-so-free. Note: nearly all enterprise-level XML editors have 30-day trials,  but it’s tough to get enough done in a 30-day evaluation of DITA and the XML  editor if you’re just starting out with topics and DITA.

     

    Awareness of DITA is not always an easy achievement, apparently, and when  you’re new to DITA, it’s tough to evaluate “DITA aware.” So I guess you just  need to trust others when they say an editor is a DITA aware editor.

     

    Free XML editors

    XML Copy Editor – this open source project has an XML editor that claims to  support DITA. https://sourceforge.net/projects/xml-copy-editor/

    DITA Storm – this is a free web-based DITA editor. You can either install it  yourself if you have a web server, or try out the ditausers.org online web-based  editor for free (use the coupon code BETA) during the evaluation period.

    Enterprise-level XML editors (with 30-day free trials)

     

    I believe that you should convince your manager you need this level of editor  if you’re serious about writing DITA topics for end-user doc.

    Bob Doyle has done an excellent job of evaluating XML editors in this  article, X Marks the Spot: Let’s Take Today’s XML Content-Creation Tools for  a Spin, complete with tables of prices, platforms, support info, all the  specs you’d need to evaluate a tool for your environment. The ones I have  installed and tried are: Adobe FrameMaker ($799), Arbortext Editor ($695),  XMetaL Author DITA Edition ($895), and Syntext Serna ($195). You would have to  determine what's right for your particular environment and preferences.

    What to do to start writing DITA topics

    Open your XML editor and start with either a concept, task, or reference  topic type. Or even start with a topic to begin with. Write some content, and  validate it as you go. Once you get a handful of topics, make a DITA map either  using the code in an XML editor or using a DITA Map editor like the Task Modeler available as an Eclipse plug-in.

    What to do to get output from your DITA topics

    You can modify the ant scripts provided with the DITA Open Toolkit for your  own builds. I was able to do a few ant scripts just based on the template files  and examples the toolkit provides. I used the “ant/ sample_htmlhelp.xml”  template to make this build file for my map file named  processfile.ditamap on Windows. Edited: to link to the  sample build file code instead of posting it here because apparently our DIV layout doesn't like  wide-width PRE areas in the middle column. Nice-to-have tools for anything beyond just evaluation.

     

    You’ll want to automate building output with Ant. The example build file  above gives you a start, and there are plenty of templates provided in the  Toolkit.

     

    Once you think about enterprise publishing, reusing topics across groups, and  so on, you’ll want to use a Content Management System. I think CMS tools for  DITA is an entirely different topic that deserves more research so I won’t say  more than that yet. To get started on larger doc sets without a CMS, use a  logical folder structure and defined file naming conventions, then use the OS  search tools to look for metadata within topics.

    A DITA map editor that either integrates with the CMS or the free Task  Modeler from IBM has a really good visual method for editing DITA maps.

    More reading

    I like the Introduction to DITA: A User Guide to the Darwin Information  Typing Architecture book available here.

    The DITA Open Toolkit User Guide and Reference is very useful as  well, and free.

    Bob Doyle, an active member of the Boston DITA User’s Group, also has a  helpful article in the E Content Magazine column, I Column Like I CM: Getting Started with DITA.

    Use Don Day’s evaluation  heuristic for editors if you want to do a full-blown evaluation for your  preferences in an authoring tool.

    Everyone must read Scott Abel’s article, 10 DITA Lessons Learned From the Trenches on the Content  Wrangler when evaluating DITA for their doc needs.

    Anyway, once you get very far with the DITA Open Toolkit you might fall back  in love with the Adobe toolkit. I’d love to hear just how far you get and  whether you fall in love.