DITA Treasures
Are you braving the wilds of the web looking for information on DITA? This post covers some of the best caches of valuable DITA assets.
Read Entire Article
Are you braving the wilds of the web looking for information on DITA? Are you hunting through dusty stacks of your library? (Yes, libraries do still exist!) Or have you mounted an expedition to a bookstore? (Perhaps more rare than a library, but they too are still around.) Well, I’m here to help. This post covers some of the best caches of valuable DITA assets.
Are you braving the wilds of the web looking for information on DITA? This post covers some of the best caches of valuable DITA assets.
Read Entire ArticleIn an earlier post, I wrote about the history of DITA and where it came from. Today, I thought I would give you some information about DITA’s current caretakers.
Read Entire ArticleOne of the results of good technical documentation is reducing calls to your product’s help desk. DITA 1.3 has added new features to help you create better troubleshooting topics.
Read Entire ArticleAs I mentioned in my last post, DITA has made remarkable strides since the 1.0 spec was introduced by OASIS in 2005. What was seen as primarily a standard for technical communications has moved into the entertainment, pharmaceuticals, heavy equipment, instructional design, and oil and energy fields. When developing DITA 1.3, the OASIS DITA technical committee saw that the user community had become more diverse. And so, to meet the needs of mixed users, the committee saw the need for three editions tailored for specific users.
The base edition is designed for application developers and people who need only the most fundamental pieces of the DITA framework. If your docs don’t need detailed information typing, this would be the package for you. This is also the edition you should use if you are developing lightweight DITA-enabled applications or if you are developing specializations that use topic as the base. Such specializations might be for data sheets, calendar event listings, or even recipes.
The Technical Content Edition is the edition most familiar to technical communicators. It is used for hardware and software manuals, online help, hover help, troubleshooting information, and online documentation.
The All-Inclusive Edition is meant for users that are developing structured modular learning materials.
An informative look at the three editions that comprise DITA 1.3 can be found in an excellent white paper written by the OASIS DITA Technical Committee
Before we take a look at DITA 1.3, let’s review how DITA came to be and how it has progressed.
DITA started life at IBM in 1999. The company had spent the 80s and 90s working to improve their documentation. They had adopted the SGML (Standard Generalized Markup Language) structured documentation standard to move towards task orientation to improve the usability of their publications.
By the mid-90s, IBM knew it had to deliver content electronically to eliminate or reduce costs associated with printed publications where possible. Electronic delivery of content brings dramatic advantages, both for the information developer and for the customer.
Around this time a new markup language was developed that was a compromise between the complex SGML and the popular new HTML (Hypertext Markup Language) for web pages. The new markup language was XML (eXtensible Markup Language).
In December 1999, IBM formed an internal workgroup to develop an XML content architecture to replace their existing book-oriented SGML content architecture. In March 2001, the workgroup introduced DITA as an internal IBM tool for producing documentation. DITA was an attempt to make a simplified XML starter set for documentation markup, one designed from the outset to encourage reuse of small content components. it was simpler than SGML and able to produce online documentation.
The workgroup made the existence of DITA public by publishing An XML Architecture for Technical Documentation: The Darwin Information Typing Architecture at the 2003 Society for Technical Communication Conference
In March 2004, IBM donated DITA to the Organization for the Advancement of Structured Information Standards (OASIS). OASIS formed a Technical Committee to explore a DITA Standard. The committee included XML tools vendors, consultants on Information Architecture and Content Management Systems (CMS), and end users of the DITA Document Type Definitions (DTD) and Schemas needed for the new DITA Standard.
In April 2005, OASIS approved Version 1.0 of the DITA specification. In August 2007, OASIS approved version 1.1 of the DITA specification. Version 1.2 of the DITA specification was approved in December 2010. And five years later, Version 1.3 of the DITA specification was approved.
Note: For an excellent and detailed history of DITA, see History of DITA.
In just 10 years DITA has made remarkable strides in such varied industries as software, gambling and casinos, pharmaceuticals, heavy equipment, insurance, and oil and energy. That list is sure to grow due to the new features in DITA 1.3. And I will take a look at those features in my next post.
The COS now enters a 60-day public review period in preparation for a member ballot to consider its approval as an OASIS Standard.
DITA offers a set of standard profiling attributes that are applicable to most elements.
Most of the names are self-explanatory. The props and otherprops attributes are meant to be generic for that you can use for any situation. The rev attribute is meant to identify material that was added or changed during a revision.
Let’s take a look at how you could use these attributes to create different versions of a document.
Figure 1 is part of a sample topic for installing a product on either a Windows or a UNIX operating system.
Figure 2 is the source material for the topic.
Your project manager tells you that you have customers that are only interested in Windows and some that are only interested in UNIX. Add into that pot folks that are using both Windows and UNIX. Which of those profiling attributes are you going to use? You got it, platform!
Figure 3 is how you have tagged the source to create docs for each set of customers.
For the customer that is interested in both Windows and UNIX, you added a platform attribute called all. Then you added an info section with only the Windows information and tagged it with a platform attribute called windows. And finally, you added platform attribute called unix for the the UNIX customers. Now, how do you get those marked sections to show itself or to hide. The answer is to create a ditaval file.
A ditaval file is used to instruct the transform what to do with your conditional attributes. Figure 4 is the ditaval file I created for the topic.
In this ditaval file, only the platform values of all will be displayed. So you would get a topic just like Figure 1 after your transform is completed. If you want to display only the Windows platform, you would edit your ditaval file as shown in Figure 5.
The resulting topic after you transform is shown in Figure 6.
And you would do the similar to create a UNIX only topic.
Now your project manager tells you that your customers want separate documentation for novice and experienced users. So you take a look at your documentation and decide that an experienced user wouldn’t need to be told what the variables (x and license_filename.lic) mean. In this case, you would use the audience attribute on selected paragraphs as in Figure 7.
Paragraphs that only a novice would be interested in are marked with an audience attribute called novice. Before you transform, you need to add the attribute to your ditaval file as seen in Figure 8.
The ditaval instructions now read to include platform attributes called windows, exclude platform attributes called unix and all, and exclude audience attributes called novice. After you transform, you get the topic seen in Figure 9.
We’re not done yet. Now your project manager tells you that have a customer that thinks desktops are history. Therefore, they want only references to the laptop. The offending word is in your short description. Do you want to create two short descriptions and label them with appropriate attributes? You could. Or you could attack the offending words directly using the tag and the props attribute as seen in Figure 10.
Note that the word or is also tagged. If it isn’t excluded also, the sentence will not make sense.
Now you add the attribute to your ditaval file as in Figure 11.
This results in the topic seen in Figure 12.
We only took a look at the platform, audience, and props attributes in this post. I think you get the idea though. DITA’s conditional processing is a powerful and useful feature.
In earlier posts, I discussed the importance of the short description
The <shortdesc> element is usually one sentence. Sometimes two or more. But your editors will tell you to keep it short. Its name is what it is supposed to be. That is, a short description of the topic it is introducing.
The <shortdesc> element is common to all DITA types of topics: Concept, Task, and Reference. It is the first paragraph in a topic. However, it isn’t mandatory. You can eliminate the element and you will still have a valid DITA document.
So why use it?
A colleague of mine, Don Day, wrote “… of all the DITA elements, shortdesc is most like a credit card with a loyalty program that rewards you for using it.”
What kind of rewards does the <shortdesc> element provide? Very simply, it allows readers to easily find the correct information for which they are looking.
Easy to find
In Developing Quality Technical Information: A Handbook for Writers and Editors, the authors identify nine characteristics that quality information shares.
If a reader can’t find information they need to use product, they can become frustrated. And most likely, frustrated readers become disenchanted users. And that leads to bad product reviews. To avoid that road, take some time with your <shortdesc> element.
Since it is the first paragraph in a topic, a well-written short description will tell the reader if it contains the information for which they are looking. A well written short description will contain keywords that will help the reader identify whether the topic contains useful information. It should be a concise description of the topic.
Here’s an example of a bad short description for a topic called “Introduction to Bird Calling” in documentation for the Acme Bird Feeder. The following topic contains instructions on how to master bird calling. After reading the topic, the reader thinks “Why should I care about bird calling? All I want to do is feed the birds.” When the short description is rewritten, the reader is given more information.If you wish to attract more birds to your Acme Bird Feeder, learn the art of bird calling. Bird calling is an efficient way to alert more birds to the presence of your bird feeder. “Ah,” says the reader. “This topic will ensure that that I alert the birds that dinner is served! I’m getting the most bang for the bucks I put out for this bird feeder. The Acme Corporation has earned my loyalty!”
If you have topics nested in your main topic, those topic titles are are automatically generated as links at the end of the main topic. (In DITA, the main topic is listed as the parent topic and the nested topics are the child topics.) Under the topic title is the text in the <shortdesc> element. A link to the parent topic is also automatically generated at the end of the child topic. The short description, however, is not listed under the link. But, you can hover your cursor over the link and the short description is displayed. (This is also the case for Related Information links.)
Short descriptions appear in search engine results. So, well written short descriptions lets the searcher know that the information required is in your document. If you put key terms in your short description, your ranking in search results will be improved. That is, your document will show up in the search results before other documents.
Effective short descriptions are an opportunity to help users easily find the correct information for which they are looking. Satisfied documentation users lead to satisfied product users. Satisfied product users lead to good product reviews. Good product reviews lead to good sales numbers.
In my previous post Big Rewards for a Short Description, I talked about the importance of the short description
The iconic "JANA Man” emblem was brought to life by JANA’s founder, Joseph A. Niland, to embody his global vision for the company. The original design featured the entire globe nestled within the figure's torso, symbolizing the company’s worldwide reach (literally, JANA around the world!). In early 1978, it was reimagined into the distinctive image seen today; and recently, it was subtly updated to include a notch in the figure's head, mirroring the ball in the JANA logo.
This evolution of the "JANA Man" represents the company’s enduring mission: to connect across continents, expand its business continually and leave a lasting global footprint. The JANA Man is more than just a design; it's a testament to the company’s ongoing journey and commitment to global excellence.
Need more information? JANA is here to help!
Contact JANA Today