Subscribe to RSS
Posts Tagged ‘DITA editor’
Getting 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.
Checking out the new DITA Users website
I was looking at DITA Storm, the web-based DITA editor, for a side project today and came across a link touting “comprehensive project-level DITA authoring and publishing experience.” I’m pretty excited about this discovery — it’s ditausers.org, a place where I can try out the web-based DITA editor on a hosted web server. And, it’s free membership right now with reasonable rates later. The coupon code is BETA, just go through the checkout system and use Coupon as your method of payment. Nifty!
As for my dabblings with DITA Storm itself, I couldn’t convince my home system administrator (my husband) to help me install it on our webserver at home. Our Apache installation would have to be upgraded (one method of implementing DITA Storm needs an Apache Web Server extension that includes PHP with XSL such as Sablotron) and I don’t blame him for turning down that work request. I didn’t want to do the upgrade myself either. DITA Users has the right idea of installing the web server for you if you just want to author and publish DITA with little backend work yourself.
DITA Storm always gets me thinking about what’s next for web-browser editors and DITA. I wonder if a concept of a DITA audit is ready for prime time? You know how you can upload and validate your HTML documents to test forW3C Recommendations compliance, or 508 accessibility problems, such as the W3C HTML Validation Service and others like it (see this list). I think that some day writers might want to upload their DITA marked up documents to test for best practices in tagging for their topics, especially for task. I believe that IBM has CSS files that automatically check on how well “typed” certain content is after going through their migration tool. For example, are ordered lists in a generic topic and should be re-written as tasks with <step><cmd> elements? Is a validation step the next thing for making sure you’re using DITA to its fullest potential?
I plan to put the feed for the DITA Users Progress blog in my feed reader list. Thanks for the free beta membership, guys!
Evaluating XML editors for DITA
At this month’s meeting, Don Day discussed “More than just another XML editor” to help us all with editor evaluations that are specific to DITA support. Our summer series of topics have been centered around tools, and next month a Quadralay rep will present “something cool.” Quadralay, the folks who bring us WebWorks, is here in Austin so we’re lucky to have some vendors in the neighborhood.
Evaluating DITA editors
Don talked us through an editor evaluation from start to finish. When they’re available, I’ll link to Don’s slides, but I’ll also do a notes dump here. These notes are my thoughts, and not a summary of Don’s presentation.
He stepped us through the classes of editors and also worked his way up to what types of use cases the enterprise users are looking for. I found the use cases very helpful. Yes, there are DITA specific features to keep in mind as well. But the installation and configuration, customization for writers, suitability for your company’s strategic format, usability, and productivity gains are the right considerations. It’s also good to hear from someone who has been working in an XML editor for a while and can tell you what to look for next, once you satisfy your first few rounds of requirements (for example, the editor has to validate XML, that’s definitely a first round requirement.)
After validation, what sets an XML editor apart? For me, on the next level is the entities support. For DITA, this support is all about how usable the conref feature is for reusing parts of content. As an example, if you want your writers to use a standard list of product names, you can use conref to bring in only the correct names from the master list. (Think of Framemaker variables).
The next level is the resource manager, how well does it handle graphics and links to external documents? Let’s definitely not make that a pain when it’s straightforward in other writing tools.
After that, consider which views your writers can see – structured, tags on or off, and try to anticipate what your writers will want in the views. For me, that’s not easy, because every writer will want a different view, but customization is definitely a needed feature. Does it have pre- and partial-rendering views (or would you rather it didn’t to help train writers to get away from output and format and focus on content?)
Additional pluses include native (or plugin) viewing of notation or namespaced data, such as SVG graphics. For hardware companies I would imagine this is a must have. For software companies, I’m still investigating how important this feature is – I imagine it’s not a deal breaker for us.
The next plus he named was the suitability of user interface features to user assistance content authoring. My guess is that this is a huge one for most writers – does the editor feel like an author’s tool or a programmer’s tool? Now, interestingly, while I was drafting this post, I read The Content Wrangler’s great summation of his recent interviews with people doing DITA implementations. It’s a top ten list — 10 DITA Lessons Learned From Tech Writers in the Trenches. My favorite gems are from number 9: Don’t Fall In Love With Software.
- Far too many technical writers fall hopelessly in love with an authoring tool for no apparent business reason.
- Software love affairs are good for vendors because they convert regular, ordinary writers into mindless, unpaid software evangelists.
- Love affairs of this sort are bad for organizations that employ technical writers because they prevent us from asking questions about our own choices, our own motivations, and the impact our personal preferences may have on the organizations for which we work. Love is an emotional thing, while business is about return on investment, profit and longevity.
This is a great post, one that I will read and re-read and tell others to read as we go through more planning for our structured authoring projects.
One item that Don mentioned that I hadn’t though of before this talk are whether the editor supports macros. (However, I also think that macro support might fly in the face of the previous “author’s tool or programmer’s tool” question.) His example macro was of a cut and paste across multiple docs with a save at the end, saving the writer a lot of time by using a simple recorded macro.
Another good consideration is the viability of the company that makes the editor you like. Will service and support be around in the years to come? That’s always a good question to investigate while testing out software to purchase.
Does the editor match your processing framework (or be made to do so?) On an enterprise level this is really important. It has to be able to get the docs in front of customers in a sensible manner without a lot of intervention (in my perfect world).
Typical authoring scenarios
Now, to me, these are authoring scenarios straight out of IBM, so your company may have different scenarios in mind. I have a few more I might add as well that I’ll be evaluating.
- Start a new topic. This one is huge for people who are accustomed to the ease of templates. How about starting a new Map though? We’re one of the few companies I’ve heard of specializing map files so that writers just have map templates that they’d fill in with specific topics. We might back off that idea as it causes a lot of specialization work, but it’s a scenario I’d like to try out.
- Clean up a topic newly migrated. This one is definitely a biggie with thousands of migrated topics, youch. But, if you only plan to write new content as topics, this scenario might not be a high priority
- Revise existing already validated content. Yes, this scenario can make or break an editor’s ease of use. How difficult is it to pick through to discover where you broke your perfectly valid document (and how much flex does the editor give you while you try to organize your structure and sentences?)
- Create conrefs and links. I think of writing a glossary using conrefs to a giant master glossary and just picking and choosing the terms that matter for your particular deliverable.
- Authoring metadata, then hiding metadata that you don’t want to read in the topic as you author. I think of the prolog in a topic with things like authors and versions, info that might get in the way of readability as you author.
- Inline alternative content in place and the ability to hide it. I think of index entries cluttering up your nice content while you author.
- Pre-rendered views and partially rendered views With this scenario, I think of whether you want to be able to view Headings in a certain font or size, and viewing other formatting renditions.
Let’s talk about DITA-friendly features
Awareness of DITA’s approach to topics, such as specialization awareness, conref awareness, and Don especially feels that CSS styling and XSLT styling, both W3c standards, are a high priority for DITA friendliness. Easy to use for topic-length content and documentation is another DITA-friendly item. Specifically for CSS, a nicety is substring matches on class attributes. Proprietary styling isn’t exactly in the best interest of a DITA effort where part or most of the goal is re-use (not just of your topics but of the processes to make the topics).
Another consideration (from the audience, I believe) is how well will the tool pick up on new releases of the DITA Open Toolkit? A responsive vendor will be well aware of us chomping at the bit for the newest releases especially for new specializations and stylesheets or transforms.
Imparted final wisdom
The business benefits of DITA are at the heart of the matter. Think of how your business plans to use DITA to help your deliverables shine… will you require new specialization to do so and therefore want a lot of design features? Or will you stick to the core info types (concept, task, and reference), and therefore move your primary criterion to customization or maintenance? As Don says, these guides will help you select top candidates, but may not reduce the selection to one very quickly, so you must represent your business’s value system in the final decision. Now, that said, his last question on his Heuristic Evaluation is “Will your writers use it?” That’s a big question to keep in mind!
I’d love to hear your thoughts on what editor evaluations you’ve done – not necessarily a discussion on “this editor is the best” but more about what scenarios we should test, and why, especially from a business case perspective.
