stc india annual conference 2015 click to edit master ... › conferences › 2015 › sites ›...

Click to edit Master title style

© 2015 IBM Corporation

STC India annual conference 2015

Anindita Basu, Vidhya V Kumar

Workshop

Writing with DITA



2

Learning goals

Hit the ground running when called upon to write in DITA

• Understand how DITA is similar to and different from other

authoring frameworks

• Determine the DITA tags you are most likely to use in your day-

to-day work

• Plan and model a document -- its structure and topic types

• Write with DITA topic types



3

Icebreaker



4

DITA introduction



5

Why can't we "just write"?

A large part of a technical writer’s job is spent in making things

simple. But there is more…much more!



6

There is more to technical writing than making things simple

Einstein's quote reflects what most of us think is the primary job

of a technical writer.

That is true.

But we also need to look at other aspects.



7

There is more to technical writing than making things simple

Einstein's quote reflects what most of us think is the primary job

of a technical writer.

That is true.

But we also need to look at other aspects.

The four tenets of effective technical writing



8

Four tenets of effective technical writing

1. Re-use

2. Sharing

3. Relevance

4. Automation



9


1. Re-use

2. Sharing

3. Relevance

4. Automation

• Eliminate redundancy• Improve accuracy• Reduce the effort to update information



10


1. Re-use

2. Sharing

3. Relevance

4. Automation


Construct your information in a way that allows other groups both within and outside your organisation to incorporate your information into their own processes



11


1. Re-use

2. Sharing

3. Relevance

4. Automation



Create your information in modules that you automatically assemble according to the needs of each individual so that they get everything they needs and only what they need



12


1. Re-use

2. Sharing

3. Relevance

4. Automation




To achieve these objectives cost-effectively, automation holds the key.



13


1. Re-use

2. Sharing

3. Relevance

4. Automation




To achieve these objectives cost-effectively, automation holds the key.



14

We write frequently about similar (and different) topics

And everything should have

been done yesterday!



15

Frequent writing requires consistency

• Mark-up (formatting)

o For example, a first level list should always be alphabetically numbered

• Definitions

o For example, a task always has an overview and a list of numbered steps, wherever it appears



16

Frequent writing requires efficiency

• Don't begin everything from scratch

o Copy and customise

• Use building blocks

o Data models



17

Standardise, define, and automate

1. Standardise text mark-up styleso For example, in MS Word, use styles

for consistent formatting

2. Define termso Create definitions of repeatedly used

terms. For example, in a user manual for an automobile firm, define a maintenance task as always having an overview and a set of numbered steps.

1. Automate where possibleo Many software products and tools to

automate common tasks such as moving and formatting content



18

We are usually not the only ones writing for our firm

Not collaborating can upset the balance!



19

Many stakeholders

1. Content writers

2. Technical reviewers

3. Editors

4. Translators

5. Publishers



20

Many stakeholders

1. Content writers

2. Technical reviewers

3. Editors

4. Translators

5. Publishers

And an agile environment!



21

An agile environment – what's that?

Many parallel developments

(sprints) happening



22

So we need a re-usable data model

• That everyone understands

• Is re-usable

• Can be shared across the

company



23

Share across the company

1. Share content

o Email?

o A corporate repository?

2. Use a company-wide

approach

o Standardise data models

across the company?

o Standard tools?



24

The problem with sharing

1. Too many groupso Sharing requires a formal

collaboration mechanism

2. Each group has different requirementso It is difficult to amalgamate all

requirementso Some requirements may conflict

3. Requirements change over timeo Changes could have disruptive

upstream and downstream documentation effects

4. A single company-wide model becomes restrictive



25

What if we use different data models?

How do we share our work?

The customisation-versus-interoperability question



26

Customisation versus interoperability

1. A standard inflexible company-wide model may not suit everyone in a large corporation

2. As requirements evolve some product lines customize the corporate data model to suit their own requirements

3. They create their own data models based on the initial corporate data model

4. Soon these models over-ride the corporate data model

5. And even conflict with each other

6. Which hinders interoperability



27

Enter DITA



28

Enter DITA

• DITA was developed by IBM

and donated to the

Organization for the

Advanced Information

Standards (OASIS).

• It is now an international

standard for technical

documentation



29

DITA

An XML DTD and architecture developed specifically for technical content



30

Any new tool must be easy to learn

• DITA is built on top of HTML – so it's not difficult to learn

• It begins with the same HTML tags that all of us are familiar with



31

Any new tool must be easy to learn

• DITA is built on top of HTML – so it's not difficult to learn

• It begins with the same HTML tags that all of us are familiar with

But DITA goes beyond basic HTML



32

You could use HTML if …

• The structure and content of information need not match up

with similar content produced by other writers on the same or

other teams.

• Consistency from page to page is not important.

• Styles and behaviour will not need to change midstream.

• You're comfortable taking on the entire responsibility for the

styling, look-and-feel, and overall presentation of the content

in all possible browsers and platforms.

… basically, if things are simple.



33

The problem with authoring in HTML

1. Difficult to make global changes

o Once you've created a set of HTML pages that follow particular

style and content guidelines, it's labour-intensive to make global

changes.

o Cascading Stylesheets (CSS) may provide some help, but often the

kinds of changes you require may go beyond what CSS can

accomplish.

o And making any change to one HTML page, you must search and

replace parallel changes in all the other pages you've created.



34



2. HTML is not extensible

o You can develop HTML content that follows agreed-upon

information typing standards.

o However as you encounter the need for new types of information,

it's difficult to extend an HTML design to accommodate both new

information types and the legacy types.

o It's also difficult to enforce agreed-upon guidelines for creating

information types.

o With HTML, you're constantly reinventing the wheel each time you

adjust your information architecture.



35




3. Difficult to determine information completeness

o HTML doesn't easily provide a systematic way to check that a set

of topics includes the full set of topics needed to document a

product feature.

o As a result, it's difficult to gauge progress, and impossible to

ensure information completeness.



36




3. Difficult to determine information completeness

4. Difficult to share across product groups or external partners

o Mixing and matching HTML that follows different content and

presentation models quickly becomes unwieldy.

o Navigation, layout, headings, and general presentation style lack

overall consistency.

o No way to do anything about it, short of reworking each

information set.

o And what happens when a partner adds another content plug-in?



37

Enter DITA



38

Enter DITA

DITA is XML



39

The benefits of moving to XML

1. Open standards

o XML provides an application and system-independent format for

sharing and exchanging content

o Also organizations can use an agreed-upon tagging system, such as

a document type definition (DTD) or other schema.



40


1. Open standards

2. Separation of form from content

o You can present the same source content in different formats - as

Web pages, printed pages.

o You can transform the presentation to give an entire web site a

new style without changing the underlying content.

o You can isolate product branding into separate presentation files

so that each brand can follow its own presentation style.



41


1. Open standards


3. Extensible and meaningful tags

o XML tags can be designed to label specific content. For example, a

PIN code in an address might use a tag called "pincode"; a step in a

procedure, "step."

o Processing systems (such as search and personalisation software)

can filter and format the content, targeting and delivering it to

specific groups of users.



42


1. Open standards


3. Extensible and meaningful tags

4. Tools

o The reliance on open standards provides a basis from which a

wide variety of tools for creating, managing, and deploying XML

content can emerge.

o It offers ways to support conditional processing, automatic linking

and link checking, and a powerful reuse model.



43

DITA extends the generic advantages of XML

1. Customised transforms make global changes easy

o With DITA and XSLT, update the structure and presentation of an

entire information set by applying a consistent, core transform.

o As global changes are applied during output, apply different sets

of global changes for different kinds of output (for example, print,

online) or for different branding requirements, without having to

edit and adjust the source each time.

o Quickly respond to customer demands for new and updated

product information.

o Automate tasks like building summary tables and listing linked

topics.



44



2. Standards improve portability

o Easily share and exchange content across product groups and

external partners.

o Use common transformation and presentation models.

o Create specialised processing to offer views and presentation of

content that is company-spcific or brand-specific.

o Transform content for reuse between DITA and other XML formats.

o Maintain arrangements with third-party partners and ensure that a

writing team remains productive through business reorganisations,

mergers, acquisitions, and spin-offs.



45




3. Linking and web management

o Create and maintain cross-topic links from outside a topic.

o Apply different sets of links in different situations. For example,

when topics are used in product A, the appropriate links for that

product are included. For product B, another set of links are used.

o When incorporating content produced by another team, add

appropriate links to their topics during processing without editing

their source.

o Even add links after topics have shipped to translation.



46





4. Conditional processing

o Tag parts of a topic by product, audience, or other characteristics.

o Include, exclude, or otherwise flag that content for reuse or

specialised presentation.



47






5. Re-use

o Reuse topics in different collections.

o Reuse content between topics.

o Maintain common elements (e.g. definitions, warnings, and product

names) in a central place.

o Assemble topics about a specific set of issues and publish them on-

demand.



48






5. Re-use

6. Focused content and better writing

o Categorising content into special topic types keeps the information

focused.

o Tools that handle metadata can enable users to search for

information based on their company role, their job responsibilities,

and their task goals.



49






5. Re-use

6. Focused content and better writing



50

Specialisation: Resolving the conflict between customisation and interoperability

Typed topic structures

1. Topic

2. Concept

3. Task

4. Reference



51

Specialisation: Resolving the conflict between customisation and interoperability

1. The typed topics represent the fundamental structuring layer for DITA

topic-oriented content.

2. The basis of the architecture is the topic structure, from which the concept,

task, and reference structures are specialised.

3. Extensibility to other typed topics is possible through further specialisation.

4. The four information types (topic, concept, task, and reference) represent

the primary content categories used in the technical documentation

community.

5. Moreover, specialised information types, based on the original four, can be

defined as required.



52

And lots more (domains, maps, … )

• The vocabulary of a domain can

take the form of phrases, special

paragraphs, and lists.

• Topics used within a domain

share a common vocabulary.

• Domains of special vocabulary

can be defined and shared

among topics.

• Domains can even be excluded

entirely, to produce typed topics

that have only the core elements



53

DITA authoring tools

• MadCap

• Structured FrameMaker

• Arbortext Editor

• oXygen

• XMetaL



54

Exercise 1



55

Exercise 1:Step 1 of 2

Write a manual on Hot Air Balloons.

At the very least, produce these artifacts:

• A ToC or an outline of the manual, with chapter titles

• 1 or 2 chapters of content

Use your favourite text editor.

15 min



56

Exercise 1 :Step 2 of 2

Mark this manual up with HTML tags.

To get you started:

• Headings: <h1>, <h2>, … <h6>

• Lists: <ul> and <ol>, with <li>

• Blocks: <p>, <div>

• Tables: <table>, <tr>, <td>

Save your manual as Version 1. 10 min



57

DITA basics:Topic types



58

DITA topic types

In DITA:

• Every topic is a complete topic.

• Every topic answers one — and just one — type of question:



59

DITA topic types

Concepttopic type

Tasktopic type

Referencetopic type



60

DITA topic types

Three main topic types:

• Concept

How does this work? Why should I do this?

• Task

How to do this?

• Reference

What else might I need to know?



61

Exercise 2



62

Exercise 2

Recast your Hot Air Balloon manual into a DITA framework.

1. Save your manual as Version 2.

2. Rearrange the content of your chapters to fit the concept-

task-reference typing.

15 min



63

DITA basics:Tags



64

DITA tags

Mapping of HTML tags to DITA

HTML DITA

<title> <title>

<h1>, <h2> … <h6> <title>

<ol> <ol>, <steps>

<li> <li>, <step>, …

<p> <p>

<img> <image>, <fig>

<table> <table>



65

DITA tags

• DITA tags are mostly specific to the DITA topic types

• Some DITA tags can be used in any topic type

• Every DITA topic needs some tags that are essential



66

DITA tags

All topic types have the same basic structure:

• ID

• Title

• Body



67

DITA tags:Mandatory tags



68

DITA tags:Mandatory tags

Topic type element

Title element

Body element



69

DITA tags

What tags are contained within the body is governed by the type

of topic.

• Concept: Much leeway. Can contain running text, images, lists,

tables, and all of these contained within sections that can have

individual titles.



70

DITA tags


of topic.



individual titles.

• Task: Prerequisites, steps, results, and post-requisites. Also, a

context tag that can contain text, images, lists, and tables.



71

DITA tags


of topic.



individual titles

• Task: Prerequisites, steps, results, and post-requisites. Also, a

context tag that can contain text, images, lists, and tables.

• Reference: Much like the Concept topic type. Contains

sections that can take text, images, lists, and tables.



72

DITA tags:Task topic type

<shortdesc>

<taskbody>

<title><task>

<context>

<steps><prereq> <example>

<result> <postreq>



73


<shortdesc>

<taskbody>

<title><task>

<context>


<result> <postreq>

The order of the tags is important!



74


<shortdesc>

<taskbody>

<title><task>

<context>


<result> <postreq>

1

2

3

3a

3b

3c

3d

3e

3f

The order of the tags is important!



75

DITA tags:Concept topic type

<shortdesc>

<conbody>

<title><concept>

<section>

<example>



76


<shortdesc>

<conbody>

<title><concept>

<section>

<example>

The order of <section> and <example> does not matter.



77


<shortdesc>

<conbody>

<title><concept>

<section>

<example>


1

2

3



78

DITA tags:Reference topic type

<shortdesc>

<refbody>

<title><reference>

<section>

<example>



79


<shortdesc>

<refbody>

<title><reference>

<section>

<example>




80


<shortdesc>

<refbody>

<title><reference>

<section>

<example>


1

2

3



81

Some generic tags



82

Some generic tags

Table description DITA tag Tasktopic

Concepttopic

Referencetopic

A table with a title, and cells that you can merge and split

<table>

A table without a title, and cells that you can merge and split

<simpletable> ×

A 2-column, untitled table inside a procedure step

<choicetable> × ×

An untitled table with upto 3 columns

<properties> × ×



83

Some generic tags

List description Tag Sample output

Numbered list <ol> 1. January2. February

A list in which the order of the items is not important

<ul> • Gold• Frankincense

A list in which the order of the items is not important and you don't want bullets

<sl> GoldFrankincense

A list of terms and definitions <dl> CatAn animal that chases mice

DogAn animal that chases cats

A list of API parameters and their definitions

<parml> atproperty

A name-value pair that …



84

Exercise 3



85

Exercise 3

Create a DITA manual.

1. Save your manual as Version 3.

2. Open Oxygen Editor.

3. Transfer your content into DITA topic types.

15 min



86

DITA content referencing



87

Reuse is not just good for the environment

• It is also a good technical authoring practice.

• Content reuse is the practice of using existing components of content to develop new "documents".

• Text-based materials are the easiest to reuse.



88

Copy and paste

• Many organisations reuse content by copying and pasting text as needed.

• This works well until the content has to be updated. It is time-consuming to find and change all those places where the content has been used.

• Not only does this waste time but you could miss content and inadvertently create inconsistencies.



89

What is content reuse?

• Reusable content is like nuts and bolts that can be reused at multiple places.

• The difference is that you don't need to create copies of a nut and bolt every time you need to use it.

• You create it only once and your tool renders it every time you publish the content.



90

Why should you reuse?

• Improvement in quality and consistency.

• Reduction in time and costs of development, maintenance, and translation.



91

Reuse reduces development cost and effort

• Development costs are reduced because the amount of content an author has to create is reduced.

• Authors do not have to research and write it again, they simply reuse it.

• Also, less time is required to review the content. When approved content is reused, it is usually not necessary to review it again.

• This frees up reviewers to do their "real job".



92

Reuse reduces translation effort and cost

• Text is only translated once: Translation memory systems (TMS) use pattern matching to match content that has already been translated. Content sent for translation is run through TMS to detect already translated text. Only changed content need be sent for translation.



93


• Translated content can be rapidly reconfigured and brand new information products can be delivered from existing elements that have already been translated, without having to send the content for translation.



94


• A large cost in translation is in reformatting content. Frequently, content must be converted from the original source format (e.g., FM, HTML) to RTF before translation. Conversion disturbs the formatting. Content in DITA is easy to automatically reformat content, regardless of language.



95

Reuse improves consistency …… if done the right way

• Consistency is similarity in definition and appearance. Consistency implies that identical content should look the same or have the same constituents.

• A maintenance task that consists of a brief description and a sequence of steps at one place in a document should always have a description and a sequence of steps wherever it occurs in the document.



96


• When there is no reuse, the chances of inconsistencies in content increases because the content has to be rewritten by many people.

• Sometimes people don't like to reuse because of the difficulty in updating all the instances of the content



97


• DITA solves the problem of updating reused content.

• This consistency leads to higher quality content.



98

You can reuse three things …

1. Content reuse: Reusing the content itself

2. Design reuse: Reusing the design of the content

3. Process reuse: Reusing the process by which DITA content is

generated



99

Content reuse by referencing (conref)

• Every element has a 'conref' attribute.

• This attribute points to any other equivalent element in the

same or any other topic.

• It is a link that establishes a use-by-reference relationship. This

is called reuse by reference.

• This allows content from one topic to be referenced in

multiple places.



100

Why reference?

• Conrefs help avoid redundant content.

• They help keep all reused content up to date and

synchronised.

• The referencing mechanism starts with a base element, thus

assuring that a fail-safe structure is always part of the calling

topic.



101

Exercise 4



102

Exercise 4.1

Use conrefs in your previous exercise.

15 min



103

Exercise 4.2

Use the information given in the document to write the

installation procedure for Linux, Windows, Mac OS computers.

15 min

docLink



104

Summarising DITA reuse

• DITA is more about information types than about document types.



105



• A topic is a chunk of information consisting of a heading and some text, optionally

divided into sections. The information type identifies the type of content in the

topic: e.g. concept or task.



106






• A document is considered to be made up of a number of topics, each with its own

information type.



107







information type.

• Because of the non-nesting structure of topics, a topic can be reused in any topic-

like context.



108







information type.


like context.

• Whenever a topic is reused it is processed consistently.



109







information type.


like context.


• Conrefs: We just discussed.



110







information type.


like context.



• DITA maps: You will see in the next session.



111







information type.


like context.



• DITA maps: You will see in the next session.

• Let us now look at specialisation – the approach that entails reuse through

processes and design.



112


• Content reuse

o Conrefs

o Topics and DITA maps

• Design reuse (specialisation)

o Topic types

o Domains



113


• Content reuse

o Conrefs

o Topics and DITA maps

• Design reuse (specialisation)

o Topic types

o Domains



114

Types of design reuse

• Topic specialisation. Applied to topic structures, specialisation is a natural way to extend the generic topic into new information types, which in turn can be extended into more specific instantiations of information structures. For example, a recipe, a material safety data sheet, and an encyclopedia article are all potential derivations from a common reference topic.



115

Types of design reuse

• Topic specialisation. Applied to topic structures, specialisation is a natural way to extend the generic topic into new information types, which in turn can be extended into more specific instantiations of information structures. For example, a recipe, a material safety data sheet, and an encyclopedia article are all potential derivations from a common reference topic.

• Domain specialisation: DITA allows the definition of domains of special vocabulary that can be shared among infotyped topics.



116

Topic specialisation

• Applied to topic structures

• It extends the generic ‘topic’ into new, more specific information structures.

• For example, a recipe, a material safety chart, and an encyclopedia article can all be derived from a common reference topic.



117

Domain specialisation

• The vocabulary of a domain can take the form of phrases,

special paragraphs, and lists -- basically anything allowed

within a section, the smallest organizing part of a topic.



118





• The highlight, programming, and UI domains are provided

with the base DITA release.



119





• The highlight, programming, and UI domains are provided

with the base DITA release.

• They are the launch pad for more sophisticated

specialisations.



120

Base domains

Domain Purpose

Highlight To highlight text with styles such as bold, italic, and monospace

Programming To define the syntax and give examples of programming languages

Software To describe the operation of a software program

UI To describe the user interface of a software program



121

Define new types of content elements independently

Domain specialisation lets you derive new phrase or block

elements from the existing phrase and block elements. You can

use a specialised content element within any topic structure

where its base element is allowed.



122

DITA design specialisation features provide for great flexibility

• Simpler topic design

• The document designer can focus on the structure of

the topic without having to foresee every variety of

content used within the structure.



123



• Simpler topic hierarchies

• The document designer can add new types of content

without having to add new types of topics.



124




• Extensible content for existing topics

• The document designer can reuse existing types of

topics with new types of content.



125





• Semantic precision

• Content elements with more specific semantics can be

derived from existing elements and used freely within

documents.



126





• Semantic precision

• Simpler element lists for authors

• The document designer can select domains to minimise

the element set. Authors can learn the elements that

are appropriate for the document instead of learning to

disregard unneeded elements.



127

DITA basics:Maps



128

DITA maps

Maps: Shows the relationships and the connectivity for a set of

disparate objects that are otherwise stand-alone entities.



129

DITA maps





130

DITA maps



• Specify which of the topics must be shown in a table of

contents

• Specify which of the topics of your document set need to be

build for a specific output



131

DITA maps



• Task 1

o Concept 1

o Task 1.1

o Task 1.2

o Example task 1

• Task 2

o …

• Task 3



132

DITA maps

Reuse



133

DITA maps

Reuse



134

DITA maps

Reuse



135

DITA tags:Map

<topicref>

<topicref>

<title><map>

< topicref >

< topicref >



136

DITA tags:Map

<topicref>

<topicref>

<title><map>

< topicref >

< topicref >

Topics can be nested, in a hierarchy.



137

DITA tags:Map

<topicref>

<topicref>

<title><map>

< topicref >

< topicref >

Topics can be nested, as in a hierarchy.

1



138

Exercise 5



139

Exercise 5

Arrange your DITA topics on to a map.

10 min



140

DITA linking:More of maps



141

DITA maps




contents



Remember this slide?



142

DITA maps




contents



• Define links between related topics



143

DITA maps

Automatic link generation:

• Sequence

• Family



144

DITA maps


• Sequence

• Family



145

DITA maps



146

DITA maps



147

DITA maps


• Family

• Sequence



148

DITA maps


• Family

• Sequence



149

DITA maps


• Family

• Sequence



150

DITA maps


• Family

• Sequence



151

DITA maps


• Sequence

• Family



152

DITA maps


• Sequence

• Family



153

DITA maps


• Sequence

• Family



154

DITA maps


• Sequence

• Family



155

DITA linking

• In-topic links

• Topic-to-topic links, from within the topic

• Topic-to-topic links, from outside the topic



156

DITA linking

• In-topic links

• Topic-to-topic links, from within the topic

• Topic-to-topic links, from outside the topic



157

DITA map:Relationship tables

<topicref>

<topicref>

<title><map>

< topicref >

< topicref >

Remember this slide?



158

<topicref>

<topicref>

<title><map>

< topicref >

< topicref >

<reltable>




159

<topicref>

<topicref>

<title><map>

< topicref >

< topicref >

<reltable>

1

2

3




160




161

Concept Task Reference

Report

descriptions

Making

document-style

reports available

to viewers




162


Topics in a row:• Default behaviour: Each topic in a column has links to all topics in the other

columns of that row, and vice versa.

• Source-only linking: A topic in one column links to the topics in the other columns

but the topics in the other column do not link back to the linking topic.

• Target-only linking: A topic in one column has links from topics in the other

columns but does not link to them.



163


Topics in a row:• Default behaviour: Each topic in a column has links to all topics in the other

columns of that row, and vice versa.

• Source-only linking: A topic in one column links to the topics in the other columns

but the topics in the other column do not link back to the linking topic.

• Target-only linking: A topic in one column has links from topics in the other

columns but does not link to them.

Topics in a cell:• The topics within a cell do not link to each other but all topics in one cell of a

column link individually to all topics in another cell of a column.

• To make the topics within a cell to link to each other, you must specify a

collection-type attribute for the cell



164

Exercise 6



165

Exercise 6

Link your DITA topics through a relationship table.

10 min



166

DITA and SEO



167

SEO

Search engines:

• Focus on specific tags in the text

• Do not understand images

• Are confused by tables



168

SEO

Tagging



169

SEO

Tagging



170

SEO

Page title

Topic title

Introductory text

Subheading

Link text

Section heading

Tagging



171

SEO

<navtitle>

<title>

<shortdesc>

<title>

<linktext>

<title>

Tagging



172

SEO

"alt" attribute Images



173

SEO

Table summary: <desc> Tables



174

SEO

Metadata

• the <prolog> elementmeta



175

Best practices



176

Best practices

Concept Task Reference

Must

have

• At least one

paragraph

• A link to a task

topic

• Context

• Steps

• At least one

paragraph

• A link to a task

topic

Nice to

have

• Conceptual

diagram

• Results

• What to do next

• A link to a

troubleshooting

topic

• UI description

• Field-value

tables,

parameters, …

Review • Description of the

UI

• Numbered lists

with instructions

• Description of the

UI

• Field-value tables

• Conceptual

information



177

Best practices

• One single file for all conrefs.

• Topic linking through DITA maps only.



178

Best practices

For SEO

• Never leave the <title> element blank.

• Use the <searchtitle> tag for a more wordy and descriptive title.

• Always give a meaningful <shortdesc>. Never leave it blank.

• Always provide ALT text for images.

• Always provide a table summary (<desc>)

• Never have an orphan topic. (use relationship tables)



179

Challenges



180

Challenges

• The writing "thinking" needs a complete reorientation.



181

Challenges

Narrative style of writing



182

Challenges

Narrative style of writing



183

Challenges


• Semantic tagging takes a while to get used to.



184

Challenges

<b> and <i> are just so convenient!



185

Challenges

<b> and <i> are just so convenient!



186

Challenges



• Short descriptions are often the hardest 2 - 3 sentences to

write in any topic.



187

Challenges

Self-referential



188

Challenges

Self-referential



189

Challenges



• Short descriptions are often the hardest 2 - 3 sentences to

write in any topic.



190

Questions



191

Resources

• DITA 1.2 specification: http://docs.oasis-

open.org/dita/v1.2/os/spec/DITA1.2-spec.html

• Topic-based writing:

http://www.ibm.com/developerworks/xml/library/x-

dita3/index.html#N97

• Writing for content reuse: http://xml.coverpages.org/DITA-

ReuseByReference.pdf

• DITA FAQs:

http://www.ibm.com/developerworks/xml/library/x-

dita3/index.html

http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html

http://www.ibm.com/developerworks/xml/library/x-dita3/index.html#N97

http://xml.coverpages.org/DITA-ReuseByReference.pdf

http://www.ibm.com/developerworks/xml/library/x-dita3/index.html



192

anindita . basu @ in . ibm . com

vidhyav . kumar @ in . ibm . com

stc india annual conference 2015 click to edit master ... › conferences › 2015 › sites ›...

Documents