Saturday, January 30, 2010

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:



No comments: