DITA XML can be daunting, especially for newcomers from authoring environments like MS Word. The fundamentals of good technical writing, however, are embodied in the DITA standard. Once you wrap your head around a few simple concepts, it is not as hard as it first may seem.
You Are Already Writing Structured Content (Without Knowing it)
Every time you write a letter, update your resume, or work on a manual, you employ structures. DITA is no different. When you write a letter, you may start off with an address block, followed by a salutation, then the body of the letter, concluded with a “yours truly.”
Similarly, structures in DITA content follow a familiar pattern: title, an optional short description, perhaps some metadata, and then the body of the content, which is the part your users will read and make use of. There’s more to it than that, but remember DITA was designed with technical writing in mind, and that it is tailored to help you write content for your users.
Topic Types Are Guides to Writing
The three main topic types—concept, task, and reference—have been designed to help technical writers in their craft. Once you understand the fundamentals of how they work, it is easy to fill them with content. Concepts are designed to cover what a feature is or what a feature is about. A task provides a step-by-step set of instructions, telling the user how to accomplish something. A reference provides additional, specific information relating to a product or feature. They help technical writers focus on the needs of the user reading the topic.
Stop Worrying about How Your Content Looks
One of the basic principles of XML is the separation of content from formatting. Back in the days when I used Word or another desktop publishing program, I spent a lot of time on the look-and-feel of my content—time that could have been better spent crafting new content.
I still get nightmares thinking of times back when I was using a desktop publishing program and had to convert the header styles by hand for a multi-hundred-page document, or painstakingly finding each instance of a product feature across a set of documents and updating it to the new marketing term “du jour.” So much of this just goes away when you use DITA XML. It allows the writer to concentrate on what they do best: writing effective content for end users.
The Tools Are Mature
Back in the early days of DITA, it was hard to find software tools fully optimized for use with DITA. The standard has been around long enough that there is a plethora of solid tools available to help the writer wanting to work with DITA. oXygen is a great writing tool. The Author mode makes it easy for those new to DITA to write within the standard, and its Text view is ideal for when you have learned more and want to finesse things at the tag level.
The MadCap IXIA CCMS provides a great platform for holding all your DITA content. It helps writers with its built-in workflows, lightning-fast search for existing content, and providing a clear visual way for working with DITA content. This only scratches the surface of available features. There are many other tools, such as Acrolinx, RenderX, Antenna House, and Miramo, designed to help with DITA content.
You Are in Good Company
There are many DITA-using technical writers out there, as well as active communities designed to help both new and experienced DITA users. Here are a few resources I would recommend checking out:
LearningDITA.com – This site offers a set of free online courses designed to take you through the basics of DITA at your pace.
dita-user Yahoo Group – This is the place to go if you have any questions about how to implement DITA. Before asking a question, do yourself a favour and search its extensive archives to see whether there is already an answer.
DITA North America Conference – This is the DITA conference, hosted annually by the Center for Information-Development Management. There’s nothing like going to a good conference and picking the brains of other DITA implementors in person.
DITA Europe – This two-day conference brings together colleagues from around the world to discuss topics like adopting DITA, Markdown, XML structures, and incorporating social media strategies.
Don’t be alone! If you need help, just reach out to the DITA community!
