Using Short Descriptions for Search Engine Optimization

Recently, Keith Schengili-Roberts and I presented a webinar on the importance of DITA short descriptions. As an advocate of short descriptions I have posted on the subject a few times in the past. The webinar, which summarized those postings, was well received.

Besides reviewing best practices for writing short descriptions, we discussed how 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 putting the webinar together, Keith pointed out another important reason for using short descriptions that I had neglected in those posts. His point is that short descriptions appear within search engine results. An effective short description is important to enhancing search engine optimization (SEO).

SEO is the process of improving the rank a site or (in the writer's world) topic has on a search engine result page (SERP).

Let's take a look at the examples we presented in the webinar.

 Searching on "build manifest feature" resulted in the SERP shown above.

Of the three results, which do you think you would click? Manifestly (sorry), it would be the first. It tells you right away that this article knows what a build manifest is. The second result is a poor short description because it simply repeats the topic title. And in the third? Well there is NO short description. No telling what you are going get there.

You can find a recording of our webinar at http://www.janacorp.com/webinars. And you can find a presentation Keith gave on DITA and SEO at http://www.slideshare.net/IXIASOFT/dita-and-seo

In the beginning...

In a previous post, I talked about the history of DITA and how it came to be. And while the post received a number of likes and comments, it was from a birds-eye view.

A colleague of mine, Keith Schengili-Roberts, recently published two excellent articles on the birth of DITA in which he interviewed two of the people directly responsible for DITA. I would be remiss as an amateur historian if I didn’t post links to these articles that take you directly back to the time that gave birth to DITA via the memories of Don Day and Michael Priestley. Don and Michael will also talk about some of the other folks that brought DITA into the world.

So click the following links and return with us now to those thrilling days of yesteryear…

• http://www.ditawriter.com/don-day-and-michael-priestley-on-the-beginnings-of-dita-part-1/
• http://www.ditawriter.com/don-day-and-michael-priestly-on-the-beginnings-of-dita-part-2/

This post was originally published at http://www.janacorp.com/blog/beginning

DITA treasures

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.

DITA Writer

DITA Writer is a great one-stop spot for blog posts and lists of DITA conferences, tools, and vendors. This site was created and is maintained by Keith Schengili-Roberts.

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA

This book by Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt is one of my favorites. You will find out what you need to know before using DITA, how to use DITA, and how to implement DITA. No link for this one, but you can buy it from most online book sellers.

DITA Demonstration Collection

The DITA Demonstration Collection provides a set of sample DITA files that are meant to be used to demonstrate selected capabilities and benefits of DITA. The files are up-to-date in that they reflect the latest DITA release (1.3). An excellent resource!

DITA Community Resources

The DITA Community Github organization serves the DITA community by providing a place for things like Open Toolkit plugins, sample content, or other utilities that don't have a better home.

DITA Open Toolkit

Do you want to develop and publish DITA content without buying DITA tools? Use the DITA Open Toolkit.

OASIS

In my previous post, I talked about where DITA calls home. You can find the latest spec as well as the previous iterations at the OASIS website. Among the finds at the DITA TC home page are White Papers information on the technical committee and subcommittees that maintain the DITA standard. On this sign-up page, you can subscribe to a public mail list for providing input to the OASIS DITA Technical Committee members.

IBM developerWorks

OASIS may be the adopted home of DITA, but it was born at IBM. Take a look at Introduction to the Darwin Information Typing Architecture for a good introduction to the DITA standard. Remember though, it was published in 2001 at the dawn of DITA. Still, it is an excellent initiation to DITA.

DITA XML.org

DITA XML.org is a community-driven site and encourages content contributions from readers.  You can find news, services, products, information, and much more. Note: The site is undergoing a refit but still is very usable and useful. 

JANA

My Home, Sweet, Home! No matter where your company is at in the DITA implementation process - from evaluation, to ramping up your DITA implementation efforts, to making the push to close out your DITA conversion program - JANA’s experts can assist your implementation efforts at any level and at any scale. We are producing DITA-related webinars and workshops. Send me a note and I will be happy to put you on our mailing list. If you have a topic you're interested in, let me know and we will develop a presentation or webinar specifically for you!

Are there any sites or books that you have found useful? Let me know in the comments below.

Where DITA Calls Home

In 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.

IBM donated DITA to the Organization for the Advancement of Structured Information Standards (OASIS) in March 2004. OASIS is a nonprofit consortium that drives the development, convergence and adoption of open standards for the global information society.

OASIS  produces worldwide standards for security, Internet of Things, cloud computing, energy, content technologies, emergency management, and other areas. OASIS open standards offer the potential to lower cost, stimulate innovation, grow global markets, and protect the right of free choice of technology.


OASIS was founded under the name "SGML Open" in 1993. It began as a trade association of  SGML (Standard Generalized Markup Language) tool vendors to cooperatively promote the adoption of SGML through mainly educational activities.

Within five years, high tech industry began to move away from SGML to a new markup language. This new language 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). SGML Open changed to OASIS to be inclusive of XML and reflect an expanded scope of technical work.

The OASIS DITA Technical Committee (TC) defines and maintains DITA and promotes the use of the architecture of creating standard information types and domain-specific markup vocabularies. The TC creates specifications for DITA and then submits them for balloting by OASIS membership.  Membership in the DITA TC is represented by over 50 companies, government agencies, and individuals.

Furthermore, there are four active DITA TC subcommittees. These subcommittees are concerned with:

• Designing online help systems using DITA
• Developing educational content that meets the needs of education professionals
• Developing educational content specializations for the tech comm package of DITA 1.3 as well as education for those specializations
• Developing a specification for a lightweight DITA architecture

If you're interested in having a say in what goes into the next version of DITA, consider joining the DITA TC or a subcommittee. Before you do so, you or your employer must be a member of OASIS.
Information on joining OASIS can be found at https://www.oasis-open.org/join

Information the DITA TC and subcommittees can be found at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita

The Top 5 DITA Conversion and Authoring Pitfalls (and how to avoid them)

Mark your calendars for May 5, 2016 to learn from two of JANA's resident DITA experts. Register for our WEBINAR at http://bit.ly/1WDOcBp

Join Stephon Johns  and me as we discuss five of the most damaging issues related to company-wide DITA implementation, and offer some good advice aimed at helping your company avoid (or overcome) them.

Looking for trouble with DITA 1.3

One 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. Let's take a look at them.

The "trouble" value

The new DITA 1.3 spec has added a new value, "trouble", for the @type attribute of the <note> element. This allows you to provide information within any topic type on how to deal with a possible error or malfunction. In previous versions of a spec, you could use the "important" or "tip" value. The "trouble" value allows you to bring a more specific reason why you would want to draw attention to the note. Here's an example of how you would code it:

<steptroubleshooting> element

The <steptroubleshooting> element is used in task topics. This element is used to explain what to do if the result of the step does not match the results documented in the <stepresult> element.

To see how it would be used, take a look at this sample from the DITA 1.3 spec.

 

 

 

<tasktroubleshooting> element

The <tasktroublehooting> element is also used in task topics. This element differs from the <steptroubleshooting> element in that it follows the <result> element. That is, where <steptroubleshooting> explains how to remedy the results of a single step, <tasktroubleshooting> helps when the results of a series of steps are unexpected.

To see how it would be used, take a look at this sample from the DITA 1.3 spec.

The troubleshooting topic

 The Troubleshooting additions to DITA 1.3 are designed to overcome the obstacles and make it easier for users to identify problem-solving information.

You may ask, "Haven't we had a troublehooting topic for a while?" Yes and no. A troubleshooting specialization was developed for the DITA OpenToolkit in 2007.  It had relatively simple sections such as Symptoms, Causes, Diagnoses, and Resolve. DITA 1.3 formalizes troubleshooting into a new topic.

As a topic-level element, <troubleshooting> contains elements such as <title>, <shortdesc>, <related-links>, etc. <troublebody> is the main body element in a troubleshooting topic. The <troublebody> element contains the following elements:

<condition>
 Describes a condition or symptom that is associated with an undesirable state in a system, a product, or a service. This is an optional element.

<troubleSolution>
Required. This element contains the <cause> and <remedy> elements. The elements are for text describing the possible reasons and solutions for the problem. The <remedy> element begins with an optional <title> element followed by an optional <responsibleParty> element followed by either a <steps> element, a <steps-unordered> element, or a <steps-informal> element. The <responsibleParty> elements indicates who is expected to perform the steps that are outlined in the remedy.

Summary 

The new troubleshooting features in DITA 1.3 will be an important resource for writers who want to get users accurate and helpful information. It will also help prove the value of the writing group when you are able to reduce calls to the product help desk.

Note: You can find the DITA 1.3 spec here.

DITA 1.3 is 3 in 1

With DITA 1.3 you get three in one. That is, the newly approved standard contains three different editions for three different audiences.

As 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 three editions of DITA 1.3 are:

• Base
• Technical Content
• All-Inclusive

The following diagram illustrates the three editions:

Base Edition

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.

Technical Content Edition

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.

All-Inclusive Edition

The All-Inclusive Edition is meant for users that are developing structured modular learning materials. Such material would include:

• Textbooks
• Online assessments and courses
• Training materials

For more information...

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: DITA 1.3: Why Three Editions?

In my next post, we will look some more at DITA 1.3.