Archive for the ‘DITA’ Category

The Dynamic Publisher

Tuesday, May 8th, 2012

A while back, Scott Abel announced the launch of the Dynamic Publisher site. If you’re interested in content managment, XML publishing, or DITA, you’ll probably want to keep an eye on this one. There isn’t a huge amount of content on it right now, but what’s there is pretty good.

Just a quick note to say that in addition to my many other roles, I’m also now the editor of TheDynamicPublisher.com. Formerly a web property used by Quark to publicize its dynamic publishing products, TheDynamicPublisher.com is now a vendor neutral home for all things related to dynamic content. You’ll find interesting articles about XML, content management, eBooks, semantic web, content conversion, content quality, as well as information about events, training, and industry news.

But, alas, I can’t do it myself. That’s where you come in. Stop by the blog and take a look around. Read some articles. Leave some comments, if you like (and I hope you do). Make some suggestions, should you feel inclined.

Guest Post: How to get DITA experience

Monday, April 30th, 2012

This question was posted on the dita-users mailing list last week. “I understand what DITA is, but have not found any employer who is willing to let me get experience in it via OJT, which is how I learned all of my other technical writing skills over the years. Any advice?”

The response that follows was posted by Troy Klukewich, Manager, Information Development, Fusion Payroll Localizations at Oracle. I’m posting it here with his kind permission.

I’ve hired numerous writers with varying degrees of DITA, XML, and structured documentation experience over the years, so I can provide some feedback.

I don’t know where you are located, but if you can, take JoAnn Hackos’ classes. She regularly holds them throughout the US and abroad. I greatly appreciate her work in structured documentation and DITA. I’m always impressed when I see that writers have taken her courses whether or not they have formal DITA experience on the job. A number of my employees have taken her courses and reported back that they are great, even when they have prior hands-on experience.

It would be worthwhile to see what classes might be available via the local universities. For instance, I know the University of Santa Cruz has a great program with a number of IBM experts driving the DITA curriculum. I’ve hired people with no prior work experience who took these courses with great results.

If you happen to have any structured documentation experience apart from DITA, this is also valuable, as I’ve found understanding how structured content works more important than the technicalities of DITA. In other words, there are people who may have DITA experience and yet still have very little understanding of the structured part, which is independent of implementation. (I worked on structured content for SAP implementations before DITA even existed.)

For those people who want experience while still at a non-DITA company, if at all possible, try to get on a skunks work project to test DITA, possibly adapting existing content as much as it pertains to any number of freely available trials for DITA tools, such as Arbortext, XMetal, and oXygen (the usual subjects in my view). In some ways, this is more valuable than working at a company that already has DITA as you have to get down into the weeds more and really think things through. (Companies can implement DITA in any number of different ways, some better than others.)

Check out DITA.XML.org for any volunteer opportunities. Also, OASIS, the standards body, unfortunately is generally too expensive for individuals, but if you can join grass roots or open source initiatives using DITA, you’ll get hands-on experience.

If all else fails, at least play with the trials yourself and maybe check out the DITA Toolkit, though the toolkit is a little bit like being exposed to a car parts factory as opposed to the completed car (in other words, great for mechanics and engineers, though it is somewhat accessible to a general audience). :-)

The main thing that managers driving DITA projects want to know is are you beyond The Book model, in other words, thinking in chapters. If you are wedded to the chapter and book model, no amount of topic-based training is going to change that preference. I’ve found that writers either get it or they don’t. If you can prove that you get it, you’re in.

Troy Klukewich

Manager, Information Development

Fusion Payroll Localizations

Oracle

Siberlogic DITA CCMS is now free

Thursday, April 19th, 2012

Siberlogic’s DITA CCMS (component content management system) is now free. From a message posted on the dita-users mailing list:

Please note that the use of the software is NOT limited to a subset of its standard DITA support functionality. Similarly, the use of the software is NOT limited to any specific number of users. Instead, the software is provided with all its DITA XML support features for any number of users on your team.

SiberSafe DITA CCMS users are not required to purchase any services in order to take advantage of the free SiberSafe DITA CCMS software. While we are happy to provide our implementation, training and support services, we do not require that you purchase any such services in order to take advantage of the free software.

SiberSafe DITA CCMS comes with a no-cost built-in XML authoring tool and is also tightly integrated with XMetaL/XMAX, ArborText, FrameMaker and oXygen. While the integrations with these 3rd party authoring tools are provided at no cost, the authoring tools themselves have to be licensed separately from their vendors (other than the authoring tool already included into the package).

This is a unique opportunity to take advantage, at no cost, of the state-of-the-art SiberSafe DITA CCMS features, including the workflow control engine, link management, collaborative online review/annotation, full text index/search, configurable content management granularity, collaborative check in/out-based authoring, version control, PDF layout design, PDF and knowledge base publishing and hundreds of other DITA CCMS features.

I’ve never used the tool, nor do I know much about it, but given that it’s now free, it should be easy enough to experiment with it to see if it meets your needs.

Guest post: A successful DITA implementation

Monday, January 16th, 2012

Guest post by Julia Malkin. This originally appeared on the dita-users mailing list as a response to a query from a list member about whether it was worthwhile for them to implement DITA.

Julia Malkin is a Principal Technical Writer at Endeca. Since 2006, she has pioneered Endeca’s DITA adoption as the DITA project lead and a member of the Information Architecture team. Julia has been following standards and best practices in the DITA arena as well as related authoring, content management, and documentation production tools since 2005, and applied this knowledge when overseeing the implementation of a new XML authoring and production environment for the Endeca Documentation team.

We have implemented DITA at my company during the 2007-2009 years, going from Frame 7 to XMetaL and SVN. The conversion was manual and took so long because we did it gradually, starting from those guides that were the highest priority and/or were new, and then moving all other guides to DITA-based on their priority. I was the project lead and, initially, along with my manager and our editor, we were the team that was both interested in DITA and knew enough to get started. From what you describe, your doc set will definitely benefit from being more modular. It is incredibly useful not having to write content twice or to maintain duplicate content. However, whether getting these benefits is worth the effort in implementing DITA depends on the following factors:

  • The willingness of the team to learn and change their ways. Your team’s success largely depends on whether everyone on the team is willing to commit their time and learn. In addition, there are many tasks in the project that could be shared along the way, and it helps tremendously if your team is willing to pick any of these tasks and drive them to completion.
  • The willingness and ability of one or two members of the team to serve as project managers. This includes creating wiki pages with information that must be shared along the way, continuous project tracking efforts through some project management software (zen, scrumworks, jira), creating and conducting learning demos/presentations to the team.
  • The willingness and ability for one or two team members to serve as information architects. This person would create the new organizational model, decide which units of information you are going to have, and how you will organize them in content sets (maps). This role also includes development of metadata, creation of XML templates for your topics and maps, naming conventions, creation of SVN directory structure, deciding which output types you are going to need and implementing them (PDF and some sort of online output that suits your needs, either Eclipse Help or other), troubleshooting and customizing the production of outputs (online and PDF).
  • Finally, there is conversion of the legacy content. At each of these stages, there are consultants and software you could use to help leverage existing accumulated knowledge, simplify and/or speed up the process. It helps, of course, if you have management support, not just at the doc team level but at the larger departmental level.

Looking back, I am happy that we are now a DITA/XML group and that we made the leap. I am also grateful for the learning and professional growth that occurred along the way. Personally, I would also switch from Frame to a native XML editor, because I believe the transition to typed XML-based content is significant enough that it warrants having a truly XML-based authoring tool. It also helps to use an XML-based editor when you must stop relying on an unstructured writing environment of FrameMaker. However, I recognize that switching editors is debatable, and that many writing groups appreciate the numerous benefits of FM, and value them more over other features, such as native XML support.

Guest post: Why DITA?

Wednesday, January 11th, 2012

Guest post by Casey Jordan. This article originally appeared as a post on the dita-users mailing list. Casey is a DITA evangelist and the co-founder of Jorsek, the creators of the easyDITA content management system: http://easydita.com.\

Update: Check out the comments – it’s an interesting thread.

DITA can be overkill for many applications. However, you also have to remember that DITA is much more than just a way to write content. It’s a philosophy and a standard which puts the user in control. Even if you are not using the full potential of the language, DITA *can* be the ultimate insurance policy on your content’s future.

It would be easy to write a whole book on all the advantages of DITA, so this is tough to fit in a single email. However, in my opinion, DITA really stands out over other methods in two regards: open standards, and native componentization of content. Regardless of how DITA may be implemented, these two things are at the core of its success.

Open standards are very important because technology changes so rapidly. With DITA, you can use your content with many different tools, customize it, move it anywhere you want, and convert it easily to other formats. There are DITA editors which are made for simple easy editing, and editors that expose a range of more powerful development tools. There are also a variety of systems that publish and serve DITA content. All of these tools can co-exist and work together harmoniously because of open standards.

More importantly though, these standards are well controlled, and transparent to the community. So the evolution of the specification can be influenced by all parties involved. Also, change is much easier to predict and address.

The second thing DITA does really well is native componentization of content, meaning DITA’s “baked in” philosophy for writing in small topics. While many tools have similar approaches, few have it so central to its core. And while this makes it easy to re-use content, it has a host of other benefits which are often more important and overlooked. For instance, separate business processes which rely on the same content can work simultaneously without blocking each other. Businesses can reduce the time for a product to reach the market, because they can develop documentation faster. This provides a huge competitive edge. Imagine if you could always release the next version of your product a month earlier than your competitors could.

While it may be hard to start on the road to DITA, the combination of these two features alone:

  • Improves employee effectiveness in transferring knowledge. (It can be authored and managed with a host of different tools suited for different user types, on different platforms.)
  • Helps business groups work together on the same content more effectively, preventing processes being blocked and reducing the time to completion.
  • Can mitigate the risk of change because of transparent open standards.

In the long run, this means fewer headaches, faster time to market, and less money spent.

XML Mind improves DITA converter

Thursday, December 8th, 2011

Pixware keep improving their open-source DITA Converter tool. The latest release adds Webhelp output – you can see a sample here.

XMLmind DITA Converter (ditac for short) allows to convert the most complex DITA 1.0, 1.1 or 1.2 documents to production-quality XHTML 1.0, XHTML 1.1, HTML 4.1, JavaTM Help, HTML Help, Eclipse Help, EPUB, PDF, PostScript®, RTF (can be opened in Word 2000+), WordprocessingML (can be opened in Word 2003+), Office Open XML (.docx, can be opened in Word 2007+), OpenOffice (.odt, can be opened in OpenOffice.org 2+).