Technical Writing ToolBox

A Blog on Technical Writing

Difference between Task, Concept, and Reference topics in DITA

Task, Concept, and Reference in DITA

Task, Concept, and Reference in DITA

Note: The content on this page is based on work done by Bernard Aschwanden of
http://www.publishingsmarter.com and is used with permission.

The Darwin Information Typing Architecture (DITA) specifies three basic topic types: Task, Concept, and Reference. However, people often get confused about these three types. Our cool (and knowledgeable) professor Bernard Aschwanden (he is an expert in DITA!) gave us an interesting exercise to differentiate between the three topic types in DITA.

Let’s look at the wikipedia definition for these three types:

Task topic in DITA

A Task topic is intended for a procedure that describes how to accomplish a task. A Task topic lists a series of steps that users follow to produce an intended outcome. The steps are contained in a taskbody element, which is a specialization of the generic body element. The steps element is a specialization of an ordered list element.

Concept topic in DITA

Concept information is more objective, containing definitions, rules, and guidelines.

Reference topic in DITA

A Reference topic is for topics that describe command syntax, programming instructions, and other reference material, and usually contains detailed, factual material.

Task-Reference-Concept Exercise

Take a look at the following text:

Potential obstacles to building wind farms include public controversy over the placement of the wind turbines, permit challenges, financing concerns, and technical issues, such as the need for infrastructure to transmit the power to the electrical grid that serves customers.

KEEP IN MIND: Hire qualified experts to assist you with each step in this process.

The first step in building a wind farm is choosing a location that has enough wind resources. The best sites for commercial wind farms have wind speed of 13 miles per hour (6 meters/second) or more, says the American Wind Energy Association. Too much wind can actually strain equipment and make the project more expensive.

Special wind speed maps will help you identify a region with suitable wind resources. For example, the U.S. Department of Energy offers wind map resources. A tool called an anemometer can help measure wind energy at the specific site. (Some states offer anemometer loan programs.) Your engineer may use specialized services and software, such as windNavigator® and GHWindFarmer, to analyze topography, weather conditions, and aerodynamics in order to optimize the location.

The above text block represent information without any clear definition of task, concept or reference. Any unstructured content, similar to the above text, would have a mix of task, concept, and reference topics grouped together cohesively as one big unit of information. However, to achieve single sourcing we must separate the content into task, reference, and concepts.

Part 1- Color Coding the Topic Types

Let’s start by defining three different color codes for each of these topics types:

Task (how do I)    — Concept (why would I, what is)  —   Reference (technical stuff, lookups)

Part2- Applying Color Code to the Main Topic

Now let’s apply these color codes to the main topic text based on the definition of the three topic types.

Potential obstacles to building wind farms include public controversy over the placement of the wind turbines, permit challenges, financing concerns, and technical issues, such as the need for infrastructure to transmit the power to the electrical grid that serves customers.

KEEP IN MIND: Hire qualified experts to assist you with each step in this process.

The first step in building a wind farm is choosing a location that has enough wind resources. The best sites for commercial wind farms have wind speed of 13 miles per hour (6 meters/second) or more, says the American Wind Energy Association. Too much wind can actually strain equipment and make the project more expensive.

Special wind speed maps will help you identify a region with suitable wind resources. For example, the U.S. Department of Energy offers wind map resources. A tool called an anemometer can help measure wind energy at the specific site. (Some states offer anemometer loan programs.) Your engineer may use specialized services and software, such as windNavigator® and GHWindFarmer, to analyze topography, weather conditions, and aerodynamics in order to optimize the location.

Part3- Separate each topic type and group them together

Now let’s group together task, concept, and reference topics:

Task

The first step in building a wind farm is choosing a location that has enough wind resources.

Concept

Potential obstacles to building wind farms include public controversy over the placement of the wind turbines, permit challenges, financing concerns, and technical issues, such as the need for infrastructure to transmit the power to the electrical grid that serves customers.

Too much wind can actually strain equipment and make the project more expensive.

Special wind speed maps will help you identify a region with suitable wind resources.

Reference

KEEP IN MIND: Hire qualified experts to assist you with each step in this process.

The best sites for commercial wind farms have wind speed of 13 miles per hour (6 meters/second) or more, says the American Wind Energy Association.

For example, the U.S. Department of Energy offers wind map resources. A tool called an anemometer can help measure wind energy at the specific site. (Some states offer anemometer loan programs.) Your engineer may use specialized services and software, such as windNavigator® and GHWindFarmer, to analyze topography, weather conditions, and aerodynamics in order to optimize the location.

So what was an unstructured chunk of information a little while ago is now divided into task, concept and reference topics.  Of course, you may not entirely agree over my definition of task, concept and reference in the example text I took since much of the information can be marked as either concept or reference.

Do you use DITA? Do you have a tip to quickly distinguish between task, concept, and reference? Leave a comment and let me know.

Advertisements

9 responses to “Difference between Task, Concept, and Reference topics in DITA

  1. whatifsometimeslifehappen June 3, 2012 at 10:04 am

    Gurpreet thanks for providing this information.

  2. adam y July 26, 2012 at 3:32 am

    Beautiful. Thanks Gurpreet. This is just what I was looking for.

  3. Alok October 22, 2012 at 4:10 am

    Hi Gurpreet, Thanks for the information. I have been using DITA for quite a while and I’ve always found IBM Information Architecture Workbench a very useful tool to do the goal and task mapping to the personas.

  4. Navatha January 15, 2013 at 6:19 am

    Thanks Gurpreet. I am not into DITA but the information put acroos is simple and comprehendable.

  5. siusan November 28, 2013 at 6:05 pm

    Our class found this useful too! Thanks Gurpreet! 🙂

  6. Sure December 21, 2015 at 4:52 am

    Hey That
    description is pretty cool…I am very new user of DITA, I am really sorry if I will ask any silly question.
    I have a doubt about “topic”, Where will I use .

  7. Franz December 22, 2015 at 4:34 am

    Nice work!
    If someone wants to know more about DITA read here: http://www.data2type.de/xml-xslt-xslfo/dita/

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: