I second Paula’s post and say the 3rd Annual Techshoret conference went extremely well. Thank you to everyone who participated.
The presentation of how we’ve implemented DITA at RADVISION, jointly given by Andy Lewis, documentation team leader at RADVISION and myself, Alex Masycheff, gathered a lot of interest. We received many questions during the session and afterwards. As DITA is increasingly attracting interest in recent years, I’d like to summarize here the most frequently questions and answers.
What is DITA?
DITA stands for Darwin Information Typing Architecture. This is a topic-based framework for authoring, managing, and publishing technical documentation. DITA defines how technical information should be structured for easy content reuse and publishing.
What are possible business cases for DITA?
These are some situations in which DITA can be beneficial:
- You extensively reuse content across multiple documents
- You have multiple content variations
- You have to customize the look-and-feel of documentation to different OEM partners or customers
- You need to enforce consistent formatting and structure
- You produce documentation in multiple formats (help, printed manuals, knowledge base articles, etc.)
- You have many different audiences with different needs and want to generate documentation dynamically
Can DITA be an appropriate solution for a lone technical writer in a company?
Yes. Any technical writer, both someone working alone and someone working in an international team, can face the challenges described in the previous question/answer.
DITA is not about the size of a documentation department. It’s about how to solve your documentation needs in the most efficient and effective manner.
What should be done to implement DITA?
DITA implementation is a multi-step process that usually involves the following stages:
1. Content strategy development
2. Content rewriting and restructuring
3. DITA customization to your specific needs (optional step)
4. Publishing templates development
5. Legacy content migration
6. Tools selection
How much time does it take to implement DITA?
As is often the case when discussing documentation and methodologies, the answer is the ever-constant, “It depends.” In this case, it depends on the goals you want to achieve, the size of your documentation team and amount of content. After quite a bit of experience, I can say that our fastest implementation took only 5 days, including all steps from content strategy development to training. Our slowest implementation to date took us several months and involved a huge amount of documentation, formats and more.
By now you are probably asking, how much time will it take to implement DITA for my company?
Well, it obviously depends on your goals. The first step is obviously to determine if DITA will work for your company and documentation needs. Is DITA right for you and your company? The best way to check it is to arrange a meeting with us so we can understand your initial requirements and outline decide whether or not DITA is a good solution for you. As part of our Techshoret special, we are offering a free consultation session.
Is migration of legacy content to DITA a painful task?
Painful? No, not really. But you should know that success of your conversion depends on two main factors:
- Consistent formatting of your legacy content: because any conversion is style-based, it depends on whether you use styles consistently, avoid ad hoc formatting, and do not permit manual formatting in your documentation.
- Organization of your legacy content: in some cases, reorganization of your legacy content may be required to make it fit the DITA topic-oriented approach. This needs to be done before the actual conversion.
Does DITA require a content management system (CMS)?
No. There are lone technical writers and entire documentation teams that are using DITA without any content management system. Eventually, as the amount of your content and complexity of products you are documenting grows, you may need a CMS to automate some tasks. However, this is not a “must-have” requirement.
How much does DITA cost?
DITA on its own is just a standard for structuring technical documentation and costs nothing. Costs are usually related to:
- DITA tools
- DITA implementation
What tools are required to work with DITA?
There are two types of tools you need to have to author and publish content with DITA:
- DITA editor to author content. There are many DITA editors available on the market today: Adobe FrameMaker, Arbortext Epic, XMetal, and many others.
- Publishing engine to generate output formats, such as PDF, HTML, and Java help.
If you are using FrameMaker as a DITA editor, you do not need a separate publishing engine to produce PDF. You can use the FrameMaker capabilities.
If you are using a native XML editor, then you will need DITA Open Toolkit (DITA OT) – a free set of stylesheets and scripts that generates various output formats from DITA content. However, be aware that you may need to configure DITA OT to meet requirements for how deliverables should look.
Can I use Adobe FrameMaker to author and publish DITA?
Yes, you can use Structured FrameMaker 7.2 or above. FrameMaker 8 and 9 already include the Adobe DITA plugin out-of-the-box. However, we recommend using the DITA-FMx plugin from an independent developer, Leximation. This plugin provides more functionality.
Stay tuned and read my next post, which will be devoted to DITA conversion tips.