Monday, August 15, 2016

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…
This post was originally published at http://www.janacorp.com/blog/beginning

Wednesday, June 22, 2016

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.

Friday, April 29, 2016

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.

Sunday, March 27, 2016

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.

Friday, February 26, 2016

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.

Friday, January 29, 2016

A Celebratory Year for DITA!


The year 2015 saw two important milestones for DITA. June was the 10th anniversary of the approval of DITA 1.0 as an OASIS standard. And on December 17th, the latest standard 1.3, was approved.

Before we take a look at DITA 1.3, let's review how DITA came to be and how it has progressed.

Information Development Before DITA

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. 
  • Electronically distributing information is significantly cheaper than printing and distributing printed publications. By some estimates, the cost of delivering an entire electronic document is nearly equal to the cost of delivering one printed page. Electronic delivery also eliminates costs associated with storing many copies of printed stock. These stocking costs include warehouse space, fees, personnel, and management.
  • Maintaining publications that are delivered electronically costs significantly less, because you pay for relatively cheaper hard disk space, not warehouse space. In addition, updating information in an electronic publication avoids the expense of scrapping obsolete copies.
  •  If you’re creating web-based documentation, you can continue developing it up until the product release date. This gives you more time for ensuring technical accuracy. And a web-hosted document can be updated as needed. You don’t have to wait until the next release or fix-pack to update a printed pub.
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).

DITA is Born

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.

OASIS

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.

Summary

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.