Quick and rude guide to DITA - Part 2 of 3

In Part 1 of this series, I said DITA was about chunks and tags, and asked you to look at this user guide. My aim was to get you thinking in terms of topic types ("Hey, this table is a reference, what's it doing in the middle of a task topic"). In this post, I'll talk of writing your first DITA topic.

DITA is XML, so you can use pretty much any text editor to write in DITA. Here's an example:

(to see a larger picture, click the picture)

Because DITA is nothing but XML, it has its own DTDs, schemas, XSLTs, etc. The DTD used in this example is the one distributed through the DITA Open Toolkit, about which we'll talk of a little later. The tags used in this example are the ones we saw here.

So, we have a DITA file. If we're writing a "manual", we will in fact have several such files. How do we organise the files into a coherent whole? We use ditamaps. A ditamap is a collection of DITA files, ordered and nested in the manner that you want. It's a tree with nodes and sub-nodes, a generated reference file where the topic files are not embedded, only called. A ditamap could look like this:

(to see a larger picture, click the picture)

Each topic is called through a <topicref> element. One <topicref> can contain many others (see the highlighted portion).

Would you want to try your hand at writing a small manual, reading which a user can download, install, and use XML Notepad 2007 of Microsoft Windows?

---

Related posts from this blog:

• Freeware for planning a DITA doc
• Freeware for writing a DITA doc

---

 

 

Quick and rude guide to DITA - Part 1 of 3

First, a DITA overview. DITA is an architecture. It is a collection of design principles that:
* Is inclined heavily towards self-sufficient information modules
* Lets its basics to be inherited into derived classes
* Borrows its tags from HTML and XHTML

To write in DITA, you need two things:
(i) Know how to think in chunks. Each topic you write must answer one - and only one - of these questions: What is this? How does it work? What should I do to make this work?
(ii) Know what tag to use where. DITA tags are XML tags, governed by the DITA DTDs and schemas.

Chunking
To keep matters simple, we'll look only at three kinds of topics: concept, task, and reference. Here's more about them (to see a larger picture, click on the picture):


Tags
Here's a list of some of the more commonly used tags (to see a larger picture, click on the picture):


In the next blog post, we'll do a short DITA exercise. In the meantime, have a look at this user guide and begin thinking in chunks and tags... (Disambiguation: Read Kai's question - in the comments to this post - and my response to Kai.)

P.S. If you really need more information, here's some reading material about basic concepts and about tags.