Topic 4: XML—the powered enabler

Extensible Markup Language (XML) is a programming language that was originally developed to make automated inter-program communication possible. It’s a data, information, or content carrier in a structured format. Today, most software use XML as its inter-operability or inter-communication standard. XML has become a norm in the industry.

DITA bases its architecture on XML. There are many other standards like DITA that use XML. But, DITA, with its other features, gives an optimum and stunning result.

The following are the characteristics of XML:

• Contains only data or information in a hierarchical structure
• Can contain any type of data or information in any structure; it’s user defined
• Can contain the definition of data, i.e. metadata
• Can contain data in any scale; some utilize XML files as small databases
• Navigating across the hierarchical structure of data is easy; can be automated
• Doesn't do any data processing or data manipulation; rather it works as an independent layer to store and pass on data to processing programs 
• Programs can read, find and decipher the data easily, and can make use of it
• Makes automated processing possible

Example: User Profile on an Online Magazine site

Account ID: PTD234G

Account type: Personal

Account Holder Name: Tony Farrell

Photo: image1.jpg

Contact information:

                Email: tony232@gmail.com

                Mobile: 8774458954

Country: US

Preferences:

Notification:

                Mode: Email

                Frequency: Monthly

                Update: Surveys

Subscription:

                                Mode: Online

                                Resources: Leadership

                                Package: Free

                                

XML structure:

XML File:

With the above characteristics of XML, in DITA, you can:

• Define your own topic type to fit to your business format
• Define small and reusable structures of information elements that can build topics together
• Define properties or attributes of data or information to fit to different contexts
• Club topics together in different combinational arrangements to suit different purposes
• Automate the flow of topics and information elements therein to different deliveries
• Can create a centralized inventory or library to store all types of reusable data or information
• Can implement faceted and automated search methods
• Use the topics and information elements therein across many software tools and programs

Practice Assignment:

• Create a XML structure showing your academic qualifications. Write a rough XML file for the same. 

Further reading:

• XML Tutorial; http://www.w3schools.com/xml/default.asp 

Quizzes:

1) What is XML?
                a) It’s a data, information, or content carrier in a structured format.
                b) It makes automated inter-program communication possible.
                c) Both a and b.

2) Which of the following is not a characteristic of XML?
                a) It contains only data or information in a hierarchical structure.
                b) Can contain the definition of data, i.e. metadata.
                c) It processes and manipulates data or information.

3) Which of the following is a valid XML syntax?
                a) <School><Class>12th</Class></School>
                b) (Language, country=”US”)
                c) /Extensible Markup Language/

4) With XML, one can define small and reusable structures of information elements that can build topics together.
                a) True
                b) False

5) Can a XML file contain data or information with a user defined structure?
                a) Yes
                b) No



Answers:
[1 c, 2 c, 3 a, 4 a, 5 a]

Topic 3: DITA’s magic information types—Task, Concept and Reference

DITA has defined three basic Information Types to start with—Concept, Task, and Reference.

Users are task oriented. So, topics instructing the users to complete user tasks are of Task type. Task topics normally contain procedures to accomplish specific goals. Each Task topic covers one separate procedure.

Before performing the tasks, the users must know and build background knowledge about the product, the service, the module, the UI, the functionality and so on, to perform the tasks effortlessly. So, topics that educate and enable users to complete the tasks are of Concept type.

While performing the tasks, users may quickly need to refer some small bits of data and information. These information are normally organized and are central-reference points, feeding information to multiple tasks. These topics are of Reference type. Users typically look for reference material only when they need it, rather than trying to study and learn it as they do with Concepts. Reference topics provide brief statements of fact, not lengthy explanations. The data here is “looked up” often and not memorized once. Information contained in lists, tables, spec sheets, etc. are good examples of reference topics.

Example

A person bought a Solar Lamp from a XYZ company. He needs to test it to check whether it’s working well or not. Here is the analysis of some probable topics:

#	Topic name	What purpose it solves	Topic type
1	XYZ Solar Lamp specifications	Provides quick facts about the technicalities and features of the XYZ solar lamp	Reference
2	About XYZ Solar Lamp	Educates about the XYZ solar lamp	Concept
3	Opening the Solar Lamp package safely	Instructs to open the solar lamp package safely	Tasks
4	Ensuring availability of all parts of the lamp in the package	Instructs to verify the availability of all needed parts	Task
5	XYZ Solar Lamp Parts	Provides a listing of all parts of the lamp	Reference
6	Charging the XYZ Solar Lamp	Instructs to charge the XYZ Solar Lamp	Task
7	Operating the Solar Lamp	Instructs to operate the XYZ Solar Lamp	Task
8	Making safe use of the lamp	Instructs to make safe use of the lamp	Task
9	Troubleshooting: Power button not working	Instructs to resolve the issue of dysfunctional power button	Task
10	Glossary	Lists names and descriptions of key terminologies used in other topics	Reference

Where is the magic?

• Whatever information we find can be generically categorized as of Concept, Task, or Reference type. 
• Concept, Task, and Reference types complement each other and together make a complete set of information that is easy to refer.
• There is a simple learning and analysis curve. Get to know the product and work with it by using only the required information. 
• Concept, Task, or Reference types form the basis for lean and minimal documentation, as any extraneous information that is outside of this Concept/Task/Reference set, are not used anyway in practice.
• Defines foundation for the evolution of custom information types for organizations. 

Further reading

• “Concept, Task, Reference: A Practical Guide to Choosing the Right Topic Type”; http://tc.eserver.org/35431.html

Practice assignment

• Prepare the outline of the User Guide for a Wireless Mouse, and categorize the included topics as Concepts, Tasks, or References.

Quizzes:

1) A topic titled as “Executive Summary”, should be of what topic type?
                    a) Concept
                    b) Task
                    c) Reference

2) What is the information type of the topic “Hospitals operating in Mumbai and their specialties”?
                    a) Concept
                    b) Task
                    c) Reference

3) What is the purpose the Concept information type solves?
                    a) To educate users about a product, service, or technology
                    b) To guide users to follow a procedure
                    c) To highlight key items in a product or service

4) Which of the following is a Reference type topic?
                    a) Closing the Wi-Fi connection
                    b) Error log file of ABC software
                    c) What makes a movie great

5) Do Concept, Task, and Reference topics complement each other in providing the whole set of information?
                    a) Yes
                    b) No

Answers:

[1 a, 2 c, 3 a, 4 b, 5 a]

Topic 2: Understanding Topics

Topics are the primary building blocks of structured authoring. The following are the characteristics of a topic:

• Tangible container or file that holds information
• Small; addresses a single subject
• Large enough to explain a subject completely and can stand alone
• Reusable across many contexts and deliverables

In DITA, every topic is stored as a XML file. Topic oriented architecture removes content repetition and makes the content reusable, thus leading to lean and minimal documentation.

Topics being basic building blocks for multiple documents

As seen in the above figure:

• Different topics connected together to form a document
• Same topic can be reused multiple times in the same document or in multiple documents
• Every topic is independent and can fit to multiple contexts
• There could be many types of documents—User Guide, Release Note, Administration Guide, and so on—all from the same set of topics.

Just like the Legos, where different shapes of blocks can be joined together to form different types of constructions.

A castle built of Legos

Practice Assignment:

• Write topic(s) to inform directions from your office to your favorite café in town.

Further reading:

• What is topic-based authoring; http://dita-ot.sourceforge.net/doc/ot-userguide13/xhtml/faqs/topic_authoring.html

Quizzes:

1) What is a topic?
                a) A discussion or conversation
                b) A complete chunk of content explaining a specific subject
                c) A section of text in a document

2) Can a topic be reused in multiple documents?
                a) Yes
                b) No

3) What is the file format of a topic in DITA?
                a) DOC
                b) HTML
                c) XML

4) Why topic based architecture provides lean and minimal documentation?
                a) Topics are written once and reused in multiple contexts and deliveries.
                b) Topic based documentation removes erroneous information.
                c) Topics are smaller than sections and chapters.

5) Which of the following is the characteristic of a topic?
                a) It explains a subject completely and can stand alone
                b) It is a single page document
                c) Topics are divided into sub-topics

Answers:
[1 b, 2 a, 3 c, 4 a, 5 a]

Topic 1: The meaning of “DITA”

DITA stands for Darwin Information Typing Architecture.

Charles Darwin had proposed the theory of evolution. Wherein he stated that everything that exist in life form today are developed from one thing, and are actually gradual evolution and specialization of the same thing. DITA uses the same principles of specialization and inheritance as the Darwin’s theory.

Information typing is the base of DITA. This makes DITA a structured content model. Using Information Types, you can structure, capture, store, and publish content. Topics that answer different kinds of questions can be categorized as different Information Types. DITA has defined three basic Information Types to start with—Concept, Task, and Reference. Answer to “What is it?” is a Concept. Answer to “How to do it?” is a Task. Answer to “Is any other info required?” is a Reference. You can specialize from these Information Types or from their parent “Topic” to have your own Information Type. Just like the different shapes of Lego blocks.

DITA is a way, a specification, or a standard, to model or design content. It defines the architecture of the content products. You can design the outline of your content product by using the rules and artifacts specified in DITA.

Practice Assignment:

Study and classify the information types for the following: 

• A section of document is titled as “About the mobile phone”. 
• A section of the document titled as “Configuring files”.

Further reading:

• Charles Darwin and Evolution; http://darwin200.christs.cam.ac.uk/pages/index.php?page_id=d3

Quizzes:

1) What does DITA stand for?

             a) David’s Infinite Typing Attributes

             b) Darwin Information Typing Architecture

             c) Direct Ideation Technology—Advanced 

2) What is an Information Type?
             a) Different types of data or information such as lists, tables, figures are information types.
             b) Valid XML documents are Information Types.
             c) Topics that answer different kinds of questions can be categorized as different information types.

3) What does ‘A’ stands for in “DITA”?
             a) Analysis
             b) Architecture
             c) Anatomy

4) What is Information Typing?
             a) The process of defining types of information.
             b) Typing data or information in XML documents.
             c) Designing the outline of documents.

5) Can you design the model of your content in DITA?
             a) Yes
             b) No

Answers:

[1 b, 2 c, 3 b, 4 a, 5 a]