The Rockley Group Blog Is Here! I have a couple of DITA questions
October 15th, 2007 | Posted in blog 18 Comments »
At the last STC Summit, I ran into the legendary Ann Rockley and interviewed her briefly about the goings-on at the Rockley Group. One of the new projects she mentioned was the upcoming launch of their stylishly-designed blog. I asked her if blogs were becoming an expected norm, and she said that yes,
People expect to see a blog, they expect to see information provided in this way.
Ann and others at the Rockley Group are interested in content re-use, which leads them into XML and DITA territory. In their latest post, they talk about a recent DITA conference they attended in Raleigh.
This brings me to the topic of DITA, which I haven’t gotten into too much in this blog. I feel like a latecomer to DITA, but two main obstacles about DITA have held me back from otherwise diving in.
In the spirit of interactive blogging, maybe Ann or Steve can write a post that answers the two following objections? Here they are:
1. DITA does not have a Webhelp format, but rather just an .chm file, which won’t display over networks. This limits DITA’s web output (apart from the network-banned .chm file) to basic HTML pages. How can DITA be so popular when its online help offering is so crippled?
2. Creating DITA content requires a detailed knowledge about the nesting of different tags (what tags are allowed in what topics, and how the tags are nested). Manually coding these tags seems very tedious. Are DITA tools still too primitive to automate the code, putting it behind the scenes? And if you have to dive into code, doesn’t it create problems for large tech pubs groups that may have many members resistant to getting so technical?
A few months ago I started reading Introduction to DITA: A User Guide to the Darwin Typing Information Architecture, but these two obstacles held me up. I was searching for a tool to replace RoboHelp, trying to decide if our content re-use was heavy enough to merit an entirely new system like DITA. Thanks Ann and Steve (and anyone else) for any thoughts you may have.
Sponsors
Tags: Ann Rockley, content reuse, DITA, Tech Writer Voices, Technical Writing, The Rockley Group
If you liked this post, keep updated with new content: Subscribe to I'd Rather Be Writing.
Both comments and pings are currently closed.
3834 Subscribers
Greg DeVore (4)
Mark Baker (4)
corporate gifts (2)
Great Clips Coupo... (2)
mma (2)
Tammy P (2)
Childrens Charities (1)
Christine Astle (1)
Keep reading.
DITA is a standard, a set of rules. It doesn’t govern what the output format is, and there are many tools already on the market that allow you to use DITA to help structure and re-use content, without having to know XML code and tags. FrameMaker for one, and many others mentioned at the X-Pubs conference in Reading this year (x-pubs.com).
The use of DITA is a way of ‘marking’ chunks of information as a particular type of information. The working group that created DITA decided that, as a base starting point (because you can extend DITA if you want) most chunks of content (known as Topics) were either Concept, Task or Reference focussed.
I’ll stop there as I could go on… and I will on my blog soon!
DITA Help output isn’t limited to .chm files. (That would have been a deal-breaker for us!) The DITA XML.org site has a list of available output formats here:
http://dita.xml.org/output-formats
That’s not to say that there aren’t other issues and challenges surrounding Help generation from DITA content. There are plenty of them. However, these kinks are getting worked out slowly but surely. We’re currently going through this pain, but it’s getting better.
Regarding your second point, creating DITA content CAN require a detailed knowledge about the nesting of different tags–but that all depends on which tool you’re using to develop and manage your DITA content. The tool that we’re using does not require our authors to understand all of the ins and outs of XML tagging and nesting. However, this knowledge can be helpful; for example, authors with XML knowledge can go directly into the XML code to do manual tagging that our WSIWYG XML editor doesn’t support.
I also plan to post more DITA-specific topics on my blog soon. I’m still trying to figure it all out too!
If you are looking to produce Help style output and other online formats from DITA content – you may want to take a look at the latest release of ePublisher from WebWorks that allows output in various different online formats from DITA content.
On a related note, I should’ve mentioned that I attended a workshop by Steve Manning (part of the X-Pubs conference) and can highly recommend anyone taking the opportunity to do the same. I also had the pleasure of sharing dinner with him, and I can recommend that too!
Before you drink the DITA Kool-Aid, take a look at DocBook (docbook.org is a good place to start). That, with the XMLMind editor, should do the trick for just about every task you encounter. If WebHelp is your thing, check out http://scottnesbitt.net/techdocs/WebHelp_with_DocBook.html.
All the best,
Tony DaSilva
Thanks for the tip. It seems like DocBook was left behind with all the buzz about DITA. Isn’t the trend among the tools to support DITA rather than DocBook?
Thanks for the recommendation. I haven’t met Steve before, just Ann.
Thanks Alan. 6 months ago a friend of mine mentioned that ePublisher was going to produce the Webhelp style output for DITA, but I didn’t know they had already finished. Sounds expensive though. Is it? And doesn’t this go against the grain of all the other outputs that are theoretically free through the DITA toolkit? Why can’t the DITA toolkit itself provide the output?
Deb, thanks for the link — I checked it out. I remember seeing Eclipse help and thinking that it would be a perfect replacement to the RoboHelp style webhelp that I’m used to. However, someone told me that installing Eclipse is extremely difficult.
I’ve been wanting to do a podcast on DITA for a while, particularly by someone who is not a vendor and who is actually implementing it. Are you interested?
What tool are you using as your DITA/XML editor?
Thanks Gordon. I think I am familiar with DITA enough conceptually, and I know there are a number of different outputs supported by the Open Source Toolkit. Maybe I’m just waiting around for someone to create the XSLT style sheets that will transform it into the nice little output I want.
Just curious, are you using DITA? Why or why not?
Short answer, not yet, but we will be.
As for DITA vs DocBook, my basic understanding is that DITA offers a smaller set of elements to start with, you can then build (specialise) on them to get to where you want to be. DocBook offers a large set of elements, a lot of which may be redundant but you’ll need to do less work on the DTD.
DITA is very much focussed on task-based documentation, and has been built to suit.
Basically spot on, Gordon. With DocBook, you use what you need and ignore the rest. And, yes, DITA was designed with task orientation in mind.
That said, writing tasks in DocBook is dead easy. The element “encapsulates a procedure providing an explicit location for summary information, identifying prerequisites for the task, examples, and pointers to related information:”
task ::=
(blockinfo?,
(indexterm)*,
(title,titleabbrev?),
tasksummary?,taskprerequisites?,procedure,example*,taskrelated?)
As for DocBook being left behind, don’t count on it. The DocBook TC just let loose the last of the v5 release candidates and is set for a November final release. Development is active and ongoing, and the community remains large and continues to grow.
Tom,
Eclipse isn’t hard to install; it’s a standard install file in Windows (though you must have a Java virtual machine in place). Updating and finding new packages can be tricky (though the Update Manager in the current version 3.3 works quite well).
I believe there’s a list or Yahoo Group for people making Eclipse help, but I don’t have that information handy. The DITA-Users group is also a helpful bunch (as are the DocBook-Apps folks). That info is on the dita.xml.org site.
Tom, thanks for the kind comments on the blog.
My answers to your questions:
1. There are three types of HTML/Help that come with the toolkit: xhtml, eclipse, and chm. People have either made do with those or have extended the stylesheets to create something custom. Of course, others have already given you that information.
2. At the DITA 2006 conference in Raleigh, Don Day and some of the other luminaries of the DITA Technical Committee were discussing the “tipping point” — the point at which DITA could be declared as a main stream solution and no longer “bleeding edge.” They felt the tipping point would come with the development of the tools. When the tools effectively support the DITA spec it would recede from the bleeding edge and enter the main stream.
Tools are much better now than then. There are tools like In.visions Xpress Author that can pretty much hide the XML from authors, to support the techically-shy (:-)) Frame does a reasonable job at hiding the XML. Even XMetaL and Epic give you multiple views so you can see the tags if you want.
So I’m not sure if the tools have pushed DITA over the “tipping point” but there are definitely tools for all kinds of authors.
/steve
Gordon,
Thanks for the kind words re. Xpubs. That was a good conference. I also enjoyed that dinner. Maybe we can repeat the experience at next year’s Xpubs.
Thanks for the reply, Steve. I was wondering when you’d see the incoming link to your blog. I received a detailed tutorial on Xpress Author, and I’ve also played around with DITA Storm for a little bit. Re eclipse, maybe I’ll look into that a bit more.
[...] .chm file) to basic HTML pages. How can DITA be so popular when its online help source: The Rockley Group Blog Is Here! I have a couple of DITA questions, Id Rather Be [...]
[...] The Rockley Group Blog Is Here! I have a couple of DITA questions | I’d Rather Be Writing on October 20th, 2007 12:28 pm [...]