Where is the user in the guide

Yesterday, I got myself a new phone. Last time I had bought one, it was April 2004 - a time when cellphones here did not have built-in FM radios, internet support, multimedia messaging, and all such exciting features that are so much passé today. Consequently, it was a very celliterate me that held the phone gingerly and regarded its QWERTY keyboard with interest. And thence started my frustration. I could not figure out how to do any of those exciting features that all phones have nowadays (let's not blame the UI now.  All UIs seem non-intuitive to first-time users).
So, I reached for the user guide. A glance at the ToC, and I could not find answers to any of my three questions.

To magnify the picture, click on the picture

"So what", I told myself. "Just a 37 page booklet. I'll flip through it and will surely find something."

Five minutes later, I threw the booklet away, powered my laptop on, asked Google, and found answers to all my questions:

• How do I transfer a photo taken on the phone to my laptop?
• Where do I get the Missed Calls list?
• How do I disable the keypad beeps?

I see several things wrong with this user guide but the one thing that stands out prominently is - this guide is describing the features of the phone; it's not describing the tasks I, the user, do.

Of currency notes and information

Today, I want to talk about currency notes. Indian currency notes, to be precise. Someone asked me, "How many languages are spoken in India?" Sighing with relief that the question was not the more usual "You all don't speak Indian?", I leaned over, pulled the wallet out from my pocket, extracted a 100-rupee note, flipped it over, counted something, and declared, "Fifteen officially. Not counting Hindi and English."

Users find information in the most unlikely of places. Had I been a "normal" user, the kinds that a techwriter would have had in mind while documenting something, I'd have gone to the Constitution of India website and referred to Schedule 8 - the place that lists all official languages (22, actually, till date, not including English). If I didn't know that's where the official languages are listed, I'd have run a Google search (which, in turn, leads me to the Eighth Schedule anyway). But I am not a normal user - just like most users are not normal users. Most users get their information from places that the writer might never have dreamt of.

The currency note designer, on the other hand, is very well aware of the implications of the panel that I referred to.

It is intentional - it's been put there to remind people what a greatly diverse country we are. I should know. I used to be part of our currency presses once upon a time. We used to call it the language panel. It's almost - but not quite- an easter egg *.

Which led me to wonder - do technical writers put easter eggs in their documents? I've not seen any but would love to know.
============================
* More on easter eggs: Wikipedia link

Am writing a book

I am writing a book on DITA.

Yes, there are, already, books on DITA. Why, then, am I writing one? Because:

• I think this book closes the gap between "what is DITA" and "how can I write in DITA".
• I had wished for a book like this when I had started off with DITA.

XML Press is bringing the book out next year. Here's more on the book: Authoring with DITA.

The Myth of the Holy Cow

In my life as a technical writer, I have been handed out quite a few myths [A myth, says the Oxford dictionary, is a traditional story], myths that come disguised as commandments that resound with a Thou Shalt Not. The intention, I suspect, is to lull me to passive obedience. In this blog post, I will mention some of these myths and what I think (and do) about them.

Passive voice has no place in technical writing

Before I state my position on this myth, let us recollect the definition of voice: the form of the verb that shows the relation of the subject to the action. So, the voice of a sentence shows whether the subject actively took ownership of an action and did it, or was so passive as to only be the recipient of the effects of the action.

Picture source: http://www.chumpysclipart.com/illustration/1199/picture_of_a_soccer_referee_being_hit_on_the_back_of_the_head_with_a_soccer_ball

Now let us look at the structure of a very simple sentence expressed both in active and passive voice.

Active: The installer copied the WAR files to the installation directory.
Passive: The WAR files were copied to the installation directory.

This example is a simple example and I wouldn't really prefer one voice over the other. But, consider the following example:

License key definitions are stored in a license key file, which, by default, is named lkad.dat and located in the product installation directory. If you need to modify the list of authorised servers or users, edit the license key file with any text editor.

Is there any reason why the first sentence needs to be turned into the active voice? Is there any reason why I want to know who is doing the storing action? All I want to know, if I am a license administrator, is where the file is stored (by whoever – I don’t care), what it is named, and how I can edit the license definitions it contains. Passive voice works here, and marvellously.

Upshot: When I think the doing of an action is important, I write in active voice. When I think it doesn’t matter who or what did or caused the action so long as the action got done, I don’t spend any time changing a passive voice construction to active.

Writing must be gender neutral

With all respect to all kinds of genders on this earth, I think that’s a piece of unholy baloney. In English, there is no grammatical gender. But, even though we write in English, there's every likelihood that the text will be translated to at least one language other than English. Many of these non-English languages have grammatical genders. The nouns have genders, the verbs are conjugated based on the gender of the nouns, and so on. So, something that is gender neutral in English can very well turn into a gendered phrase in a language like, say, French or Hindi.

My take is that spending anything more than 5 minutes on rephrasing an otherwise understandable and acceptable-by-usage English sentence into a gender-neutral sentence is nothing but a waste of time.

Every list should be preceded by an introductory sentence

The logic is, if I suddenly start a numbered list that has steps to perform a specific task, but do not introduce the list with a stem sentence, readers might be misled, confused, misinformed, etc.

Now, let’s see the following example:

1. Use one of the following methods to start the Manage Information Catalog wizard:

    * From the Windows desktop, click Start > IBM DB2 > Set-up Tools > Manage Information Catalog wizard.
    * At a command prompt, enter db2iccwz.

The Manage Information Catalog wizard opens.

2. Select the Migrate metadata from an existing information catalog option.

3. Enter the required information on each page of the wizard and click Finish.

To me, it is apparent this is a procedure for migrating your data from an existing catalog to a new one.  To my users, who are undoubtedly smarter than me because they are database administrators [audience, audience], it is very apparent that this is a procedure for migrating data from an old catalog to new; my users just do not need a stem sentence that goes:

To migrate metadata from an existing information catalog:

The title of the topic would, in any case, always have an indication of what is contained in the topic. The stem sentence adds nothing of value to the content except increasing the word count.

However, I have also come across procedures where, if a stem sentence were to be absent, important information would be missing. Here is an example:

The following steps are needed only if you overrode the default options when you installed the product.

The end result – I leave out stem sentences if I think there’s no value add in having them.

Leave the comparatives and the adverbs alone

I am in complete agreement. Whether an application is quickly installed, easier to use, and fastest in terms of response time is a conclusion best left to the user to arrive at. Technical writers are supposed to report facts, not hand out value judgements.

Computers (and computer applications) do not possess human characteristics, so, do not anthropomorphise them

I agree.
Did I hear someone say, " A piece of software does guide, control, direct my actions. Microsoft Excel lets me create spreadsheets but it does not let me create documents. An umbrella shields me from rain; a car gets me from point A to point B. It’s perfectly okay to anthropomorphise."

Picture source: http://www.wpclipart.com/cartoon/animals/fish/fish_with_umbrella_cartoon.png.html

I disagree with this line of reasoning. When someone says, "The umbrella shields me from rain", that is not anthropomorphism. That’s just someone using a verb correctly because that is indeed what an umbrella does – it shields people from rain. That is an action, not a human characteristic. Now, if someone were to say, "My brave umbrella valiantly tries to shield me from rain but fails", now that, my friend, is anthropomorphism because the umbrella has become possessed of the human characteristic of braveness (and chivalry, perchance).

Me? I let my software detect conflicts and resolve them but I do not expect it to be remorseful when it crashes my desktop.

A procedure should not have more than 7 steps
If anything takes more than 7 steps, says the stricture, break the procedure up into smaller logical pieces. I am guessing this comes from the assumption that readers have short attention spans. I said "guessing" because though I’ve been told there are studies that prove a decrease in comprehension levels after Step 7, I am inclined to believe if someone’s life depended on it, that person would read even War and Peace from cover to cover.

That said, I do try to keep my procedures as short as possible. But, sometimes, the products we write for do have procedures that cannot be fitted into the 7-step-frame. For example, can the instructions to install a rack-mounted server system really be covered in 7 steps?  Really?

Conclusion
So, is the cow holy? Well, it depends.

[A slightly different version of this blog post was published in STC India's magazine INDUS.]

DITA tools - 4 (Authoring)

I've had quite a few of my friends say, "Well, yes, we can do the information typing and we also totally get the semantic tagging concept of DITA but when we get down to actually writing in DITA, it is a bit of a hassle trying to remember all the tag names and where they are allowed. Is there a free WYSISYG editor for all this?"

In a previous blog post I had mentioned one such DITA authoring tool. In this blog post, I will talk about another.

The Serna XML Editor has a free edition that I've been using the past couple of weeks to do some personal stuff in DITA. For DITA authoring, I really like it and for the following reasons:

• It comes bundled with the DITA open toolkit. I don't have to download and install the OT separately.
• It also has DocBook (which is next on my personal ToDo list).
• Its validators will not let you insert a DITA tag at a place where the tag is not allowed. You will be shown a list of allowable tags, with hovertext for each tag.
  
  
  

  

  To see a larger image, click on the image

• It lets you define the attributes of any element through an element-specific wizard page.
  
  
  

  

  To see a larger image, click on the image

• It lets you drag and drop elements. This is something we (writers) take for granted in our word-processing software but not many free XML editors have this feature.
• It is WYSIWYG - not only in terms of DITA tags but also for output previews. To my knowledge, no other free XML editor gives a preview of the output.
  
  
  

  

  To see a larger image, click on the image

• It comes bundled with a transform engine (that's how it has the inbuilt output preview feature). This means you don't need a separate software for running the transforms. You do, however, need the JRE (if you want to publish to XHTML) and FOP (if you want to publish to PDF) - both of which are free to download and easy to install

The Syntext Serna Free XML Editor can be downloaded from http://www.syntext.com/products/serna-free/.

Some of the 'cons' that I've noticed thus far (I am not sure if these are a restriction for the free edition):

• The glossary specialisation, though supported, does not result in transformed XHTML files.
• Bookmaps, though supported, don't get transformed.

Writing in DITA - Tips #4 to 10

A verbose version of these tips was published in the Mar-Apr 2010 issue of STC India's newsletter, INDUS, as DITA writing tips.

4. To conref dissimilar elements, wrap the source text in <ph>
5. To prevent all topics of a <reltable> row from linking back to each other, use the 'linking' attribute of <topicref;
6. To include pretty much anything in a <step>, insert an <info>
7. To preserve the formatting of a copy-pasted text snippet, use <pre>
8. To have topics show different titles in different scenarios, use <titlealts>
9. To caption images, use <fig> as container for <image>
10. To have a slightly longer <shortdesc>, put it in an <abstract>

To conref dissimilar elements, wrap the source text in <ph>

DITA is about content reuse - with a rider. Only like can call like. I cannot, for example, reuse a <step> as an <li> - if I want to reuse the text of a <step>, I can conref it only from another <step>. This becomes a bit of a hassle - say, I have written something in a <shortdesc> in a concept topic that makes perfect sense as the <context> of a task topic, how do I conref it? By using the <ph> tag.

To prevent all topics of a relationship table row from linking back to each other, use the 'linking' attribute of the <topicref> element

The relationship tables in DITA are an extremely useful tool for maintaining, at a single point, the linking between all topics in a book. Each row in the table represents a discrete relationship and all files in a row link back to each other. But sometimes I end up with more links than I really want. To prevent that, I qualify the <topicref> tags with either a sourceonly attribute or a targetonly attribute. When a <topicref> has a sourceonly attribute, a link is generated to the target topic only in the source topic; when it's targetonly, a link is generated to the source topic only in the target topic.

To include pretty much anything in a <step> tag, use an <info> tag

When describing procedures, sometimes it becomes necessary to include things such as pictures, code snippets, explanatory notes, and so on. But a <step> tag can contain only a <cmd> tag and then a bunch of other tags that are pretty useless for pictures, notes, and code. The workaround is to insert an <info> tag after the closing <cmd>; an <info> tag can contain pretty much anything.

To preserve the formatting of a copy-pasted text snippet, use <pre>

Because DITA is XML, anything enclosed within < > is interpreted as a tag. So how do I include, for example, a code snippet that contais angular brackets? I wrap the text in a <pre> tag, just like I'd have done if I were writing it in HTML.

To have the topic show different titles in different scenarios, use <titlealts>

I use <titlealts>, with which I can specify two additional titles: a <navtitle>, which shows up in the ToC pane, and a <searchtitle>, which shows up in the search results page. I make these two titles slightly more verbose than the actual page title, so that they make sense even when seen outside the context of the page content. In the absence of a <titlealts> tag, the title displayed in the ToC and in the search result page defaults to what's contained in the <title> tag.

To caption images, use <fig> as container for <image>

The easiest way to put an image in a topic is by using an <image> tag. But, according to the DITA language specification, an <image> tag cannot contain anything other than alt text. How do I caption my images? By wrapping the <image> tag in a <fig> tag, which can contain not only a <title> tag but a host of other useful ones such as <desc>, <note>, and <codeblock>.

To have a slightly longer <shortdesc>, put it in an <abstract>

The <shortdesc> element is what I use for writing the "click-through text" for the topic - the text that shows up in search results and in hovertext for links. Mostly, my short descriptions contain 2-3 sentences that sum up the topic. But sometimes, just sometimes, I feel the need to write a longer short description. I'd still like to retain the shorter short description as the "pull text", but what if I want to add another two sentences and want to have them all in that section itself - the first section on a page - instead of carrying the extra sentences over to the body of the topic (where they'll probably have to reside after a <prereq> and, thus, lose all sense of connect)? In such a case, I use an <abstract> tag

DITA 1.2 - New <task> elements

The DITA language specification v1.2 introduces two new task elements: <steps-informal> and <stepsection>.
The <steps-informal> element is for describing procedural information that is otherwise not normally described as a step. The <stepsection> is for giving explanatory information before a step. It is contained within the <steps> element and can be placed betweeen two <step> elements; the output of the content of a <stepsection> will not contain a bullet or a number.

When should I use the <steps-informal> and <stepsection> elements

<steps-informal>: The v1.2 language specifications haven't yet included an example of the <steps-informal> element so I am still a bit unclear about how and when to use it.
<stepsection>: If I am using DITA v1.1 and need to give some info before a step, the only way I could do that was insert an <info> in the previous step. With <stepsection>, this problem is resolved. Here's an example (taken from the v1.2 lang specs doc):

<steps>
  <step><cmd>Get out a bowl</cmd></step>
  <stepsection>The next two steps are very important!</stepsection>
  <step><cmd>Put on safety gloves</cmd></step>
  <step><cmd>Put on goggles</cmd></step>
  <step><cmd>Pour milk and cereal into the bowl</cmd></step>
</steps>

Related information

With v1.2, a <step> can have an <note> before the <cmd>.

  

DITA 1.2 - New <topic> elements

The DITA language specification v1.2 introduces two new topic elements: <bodydiv> and <sectiondiv>.
The <bodydiv> element is intended to be used as a grouping element for containing logical blocks of info that otherwise do not need either a title or a separate topic. It can be placed only within a <body> or within another <bodydiv>.
The <sectiondiv> element is similar to the <bodydiv> element except that it has more container elements - it can be placed within a <section>, <sectiondiv>, and a bunch of other tags depending upon the topic type.

Why and when should I use <bodydiv> and <sectiondiv>

If I want to reuse a whole group of info somewhere else, these two tags are handy. Not that such reuse couldn't have been done otherwise, but then, these tags can, for example, contain several <p> elements, some lists, some images...it's almost like being able to reuse an information chunk instead of individual tags. Without being actual formal topics, these tags behave like topics.

Related information

The <concept> topic type also has a new element in v1.2 that's similar to <bodydiv> and <sectiondiv>. It's called <conbodydiv>.

History of <topic> elements

Here's a list of the various topic elements from v 1.0 to 1.2:

DITA 1.0	DITA 1.1	DITA 1.2
dita	-	-
topic	topic	topic
title	title	title
titlealts	titlealts	titlealts
navtitle	navtitle	navtitle
searchtitle	searchtitle	searchtitle
-	abstract	abstract
shortdesc	shortdesc	shortdesc
body	body	body
-	-	bodydiv
section	section	section
-	-	sectiondiv
example	example	example
related-links	related-links	related-links

Writing in DITA - Tip # 3

While authoring, I often need to refer to that specific directory, that particular URL, this specific file which resides in this specific directory. As the software development cycle progresses, names change (and how). By the time people are ready for bit freeze, I am out of my mind worrying if all the specific references I put in your doc are updated (specific references are more "consumable" by a user). But if I've had the time to plan, I'd have probably envisaged such a scenario and prepared myself. How? I give here two alternatives (there could be more but I don't know of them yet). And, because I am making a case for Alternative 2, I'll shoot down each of the examples that I give for Alternative 1.

Alternative 1

Do not use specifics. Talk in generic terms. Examples:

• From the Sun website, download the latest version of the Java Development Toolkit.
  Problem: For all you know, Sun might be acquired by Moon, and the JDK be renamed to Lunar NetBeams.
  
• In the installation directory of the software application, look for a file with a name that has a suffix that correspond to the product acronym as listed in the Offical Acronyms page of the software application.
  problem: Which software application? You said Package A was prerequisite for Package B so I downloaded both from your website and installed them and they seem to be installed in the same directory - the directory name is the name of your company. Which subdirectory of the installation directory? There are no files in the main directory. Where is the Acronyms page? The first three hits in Google lead me to pages not maintained by your company.
  

Alternative 2

Use the conref facility provided by DITA.
DITA is about content reuse.  We might as well rephrase that to say, "DITA is about reducing maintenance overheads". (<aside>The first sentence talks about a feature.  The second about a benefit. Users look for benefits (what's in it for me), not features.  Am a bit puzzled why so many techcomm people keep using the first sentence without, ah, repurposing it for the target audience.</aside>)

This is how I do it: I maintain a separate file called in which I have a bunch of text that I think are of a variable nature. Each chunk of reusable text is wrapped in a <ph> element and given an ID. Like this:

Then, in the main files, I just conref these <ph> chunks. The text comes out looking like this:

DITA tools - 3 (Transforming)

To transform dita files to a publishable output, such as XHTML or PDF, we need to run ANT builds, and we do it through the DOS command line. Another option is to use a GUI. I find the WinAntEchidna GUI, developed by HyperText, to be very handy.

The first time that you use WinAntEchidna, it asks you for the installation directory of the DITA OT (this, like all parameters, can be changed any time). Thereafter, every time you run WinAntEchidna, all you need to do is specify your ditamap file, your output folder, and your output type.

WinAntEchidna can be downloaded from http://sourceforge.net/projects/winant-echidna/.

Quick and rude guide to DITA OT installation

The install guide that comes with the DITA OT package is good (really, no sarcasm) but it sometimes assumes I am more of a techie than I really am. Last week, I changed my computer. It was while setting up my DITA environment that I remembered again that if I just follow these instructions to the T (see picture), I am more than likely to stumble.

So, I am writing up this blog post as a note to (i) myself, should I need to do this all over again (ii) everyone of you who wants to set up a DITA environment with minimal fuss. (<aside>I know; "minimal" is subjective.</aside>)

I use a Windows machine; these instructions are for a Windows setup (64-bit).

1. Download JDK. The latest version is JDK 6 Update 18 and can be downloaded from http://java.sun.com/javase/downloads/index.jsp. The file I downloaded is called jdk-6u18-windows-i586.exe.
2. Install JDK to a directory of your choice. To do so, double-click the jdk-6u18-windows-i586.exe file and follow the onscreen instructions. Stick to the default options. For the remaining part of this procedure, let's assume the JDK installation directory is C:\Program Files (x86)\Java\jdk1.6.0_18.
3. Download HTML Help Workshop. The file is called htmlhelp.exe and can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en.
4. Install HTML Help Workshop. To do so, double-click the htmlhelp.exe file and follow the onscreen instructions. Stick to the default options.
5. Download the full DITA OT package. The latest stable version is 1.5 and can be downloaded from http://sourceforge.net/projects/dita-ot. The file I downloaded is called DITA-OT1.5.1_full_easy_install_bin.zip.
6. Extract the contents of the DITA OT package to any directory of your choice. For the remaining part of this proceudre, let's assume this directory to be C:\Work_Area\DITA.
7. In the C:\Work_Area\DITA directory, look for a file called startcmd.bat, and double-click it.
8. In the command line window that opens, set the JAVA_HOME environment variable by running the following command: set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.6.0_18
9. In the same command line window, test your DITA OT installation by running the following command (which is an ANT command for transforming DITA files): ant samples.web -f build_demo.xml Wait for the command to get over.
10. Return to Windows Explorer and, in the C:\Work_Area\DITA directory, look for a folder called out. This folder was created as a result of the previous step and contains the transformed files. If you cannot find this folder, something went wrong with the installation :-(

Notes for subsequent transforms: Set the Java environment variables every time you run an ANT build, and do it from the directory where the ANT build is being run.

Related posts
Now that DITA OT is installed, you might want to get yourself an authoring tool? See this blogpost: DITA authoring tool.
Next, you might want to run your transforms, no, not through the command line, but through a GUI? My next blog post is about such a transform tool: DITA tools - 3 (Publishing).

Post script
The procedure I wrote contains several inline links, and references to specific software versions and local directories. As any writer knows, these are maintenance headaches. Whether docs can (or, should) really have such specific info, and, if yes, how to include such info with minimal maintenance overheads is explored in this blog post: Writing in DITA - Tip #3.

Writing in DITA - Tip #1 alternate solution

The problem statement is this: Cannot put link text inside <xref>.

An alternate solution is here:

Cartoon created with http://www.makebeliefscomix.com.

Writing in DITA - Tip #2

You are writing a procedure. You are, therefore, using <steps> for your list of actions that your reader needs to follow to complete the task. You have in mind something like this:

Because DITA tags are semantic, you want to enclose db2iauto -on <instance name> within a <codeblock> tag. But you hit a roadblock. You cannot include a <codeblock> tag within a <step> tag, says the DITA language specification.

What do you do now?
Insert an <info> tag after the mandatory <cmd> tag in the <step> tag. Then, insert <codeblock> within the <info> tag.
The <info> tag is pretty useful - it can contain paragraphs, lists, notes, images, ...

 

 

Writing in DITA - Tip #1

Problem statement

Theoretically, the <xref> tag can contain plain text. It must therefore be possible to write something like:

<xref format="html" href="http://publib.boulder.ibm.com/infocenter/c8bi/v8r4m0/topic/com.ibm.swg.im.cognos.ug_fm.8.4.0.doc/ug_fm_id21834Troubleshooting.html#Troubleshooting" scope="external">Troubleshooting guide</xref>

The authoring tool we use at work (Arbortext Editor) very decidedly does not think so.

So, the resulting output looks, er, ugly.

Workaround

Step 1: Insert a <desc> tag inside the <xref> tag, type something within the <desc> tag (it shows up as hovertext in transformed output), and then type something just outside the <desc> tag but still within the <xref> tag. Like this:

Step 2 (optional): Delete the <desc> tag.
Step result

Musings

I am fairly sure the problem is not a DITA bug but an Arbortext Editor bug. Anyone seen anything similar?

Post script,2 days after original post

See an alternate solution here.

Another post script, 20 days after the original post

The Arbortext people found this blog post and offered to help but by that time I had already found a solution. I am impressed by their follow-up - they are really trying to keep track of user pain points and minimising the attendant frustration. Thank you Arbortext (and Liz Fraley).
I'm still not sure, though, if it's not an Arbortext bug. The error message box is captioned "Arbortext..." and it has a bug number. The problem was I couldn't find a list of error messages (and possible resolutions) in the Arbortext help. Per my understanding, the problem seems to be - text selected within an xref tag cannot be overwritten; it can be removed only if it is not selected AND some other text is typed in AND the "generate referenced text" button clicked again. Maybe it's not a bug. But as far as I know, a standard method of deleting text is by overwriting it.  Maybe an error message section in the help docs would help?

DITA and DITA-OT

My attempt to answer a question that keeps coming my way at regular intervals: isn't DITA-OT the same as DITA?
Short answer: No. Longer answer: Read on.

	DITA	DITA-OT
What is the full form	Darwin Information Type Architecture	DITA Open Toolkit
What is it	A standard. An XML-based architecture for authoring, producing, and delivering technical information	A set of Java-based, open-source tools for processing DITA files
What is the latest stable version	1.1	1.5
Where is it	OASIS DITA Technical Committee	Sourceforge
Who owns it	OASIS DITA Technical Committee	Err, nobody. It's an open-source implementation licenced under CPL 1.0 and Apache Licence v2.0
When's the next update	1.2, under development since 2007 (track what's happening)	1.5.1, planned as a point release for DITA 1.2 and to coincide with the DITA 1.2 release

 

Help and its Usability

A verbose version of this wishlist was published in the Jan-Feb 2010 issue of STC India's newsletter INDUS.

What if my Help was not at all like the Help as we usually see it?

What if every menu option had a tiny Help button with a hovertext that tells me the consequences of a click-through.

What if there was no ToC? What if, instead of a tree of topics, I am shown only one topic? The topic that I reached by clicking the tiny Help button on the options on the menu bar?

What if every Help topic helps me orient myself with a You-Are-Here clickable flow-diagram.

What if all UI fields had examples?

What if the Help button on a UI field opened for me a page that shows the results of a predefined search – a search based on the UI screen I was at (and related to the task I was doing) when I clicked the question mark?

What if the UI had embedded cheat sheets that guide me along.

What if I had On-the-spot troubleshooting where an error message, instead of telling me what went wrong, pops up a wizard with which I can do that which should have been done in the first instance?

What if wishes were horses? Why, I'd gallop along on my tasks with nary a roadblock in sight.

 

DITA tools - 2 (Authoring)

I am very comfortable with using Notepad to write in DITA. But there are times when I forget if a particular DITA tag can be used at a particular place. For example, I regularly forget if <prereq> should precede <context> or follow. At such times, an XML editor that also validates your tags as you type comes in handy.

XMLmind XML Editor is one such tool and comes bundled with the DITA DTDs and schemas. Its personal edition is free to use for non-commercial purposes and is, thus, great if you want a WYSIWYG DITA editor for your learning and other  personal stuff.  With it, you can visually insert DITA tags, specify the attributes of the DITA elements, type your content, and validate your file (the file is valid by default because you'll be unable to insert invalid tags) - everything that an XML editor generally does.

To see a bigger picture, click the picture

The XML editor can be downloaded from http://www.xmlmind.com/xmleditor/persoedition.html.

 

 

DITA tools - 1 (Planning)

Disclaimer: IBM is my employer. But this blog post is mine own. Entirely.

The IBM Information Architecture Workbench is an Eclipse-based freeware that I find marvellously handy for organising my thoughts and then committing those thoughts to DITA files. With it, I can model my ditamaps, generate DITA stub files* for the ditamap nodes, and edit the DITA files. Plus, if I draw a line from File A to File B, it gets registered in the ditamap's relationship table. All pretty neat and clean. It shows me, visually, how my topics are arranged in my book (and lets me move around files with a drag-and-drop action). It also shows me orphan files - those nodes that I created but did not link anywhere. And, I can edit the DITA attributes very easily in the Properties view.

To see a larger picture, click on the picture

One can use this workbench for other assorted activities like Hierarchial Task Analysis diagrams and Role and Goal models but I confess I haven't been there yet. I use it as just an authoring tool. The workbench also has an inbuilt client for CVS, so I can have a multi-author scenario for my files too.

The workbench can be downloaded from https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?lang=en_US&source=swg-iiaw. To download, you need an IBM ID. Anyone can create an IBM ID for oneself - all that's asked is an email address and (I think - have forgotten) a name.

---

*Stub file: A stub file is a DITA topic file created for each of the nodes in the ditamap. Depending on the kind of file you specified while creating the node, the stub file has basic DITA tags for that topic type. The stub files can be opened with the workbench text editor, and edited like any other file. Thus, the workbench doubles up as an authoring software.

Quick and rude guide to DITA - Part 3 of 3

In Part 2 of this series, you created some DITA files. If you are a technical writer working in an organisation that's already using DITA for authoring, you wouldn't really need to bother with transforms and outputs - there will already be a system in place with which you can do a click-and-generate-output (well, almost). You need not, therefore, really bother yourself with this part (Part 3, last of the series) unless you're really eager to see how your DITA files look in HTML. If that's the case, read on.

1. In your root directory, create a subdirectory named Sample.
   
2. In the Sample directory, create three subdirectories, and name them ant_scripts, topics, and out.
   
3. In the Sample > topics directory, put your DITA files. Your DITA files must have dita as the file extension.
   
4. In the Sample directory, put your ditamap file. The file extension of your ditamap file must be ditamap. If needed, edit the ditamap file to correct the filepath reference of your dita files (because now they reside one directory lower than your ditamap).
   
5. Download and install the DITA Open Toolkit (DITA-OT1.4.2.1_full_easy_install_bin.zip).
   
6. Download and install the DITA sample garage files (ditaotug131-18042007-garage.zip).
   
7. Go to the DITA sample garage installation directory and thence to the ant_scripts subdirectory. Look for a file called garage_hierarchy_all.xml, and copy it to your Sample > ant_scripts directory. Rename the copied file to build.xml.
   
8. Edit this build.xml file as follows:
   
   • Replace all instances of DITASAMPLE_GARAGE_OUTPUT with out.
   • Replace all instances of hierarchy.ditamap with the name of your ditamap file.
     
   
   
9. Go to the DITA OT installation directory, look for a file called startcmd.bat, and double-click the file.
   
10. At the DOS command prompt, run the following command: ant -f build.xml dits2xhtml
    If your build.xml file is in a different directory than the DITA OT installation directory, specify the full path of the build.xml file. Your DITA files start getting transformed to XHTML and placed in the out directory you specified in the build.xml file. Wait for the command to complete.
    
11. Quit the DOS prompt, return to Windows Explorer, and go to the out directory. The index.html file is the landing page for all your DITA files.

That's it. You wrote some stuff in DITA, and created an HTML output. You're DITA ready :)

But wait! There's actually an easier option to convert your files to HTML without having to go through the 11 steps I listed. To create your transforms with just one single step, one single command at the DOS prompt, see this excellent article: http://www.ibm.com/developerworks/library/x-tipditajavacmd.html.

 

 

Quick and rude guide to DITA - Intermission

<task>
<title>Celebrating the World Umbrella Day</title>

<shortdesc>To celebrate the World Umbrella Day, which, according to radio reports, falls on Feb 10, 2010, get yourself an umbrella and follow the steps given in this topic.</shortdesc>

<taskbody>
<prereq>
<ul>
<li>Obtain an umbrella.</li>
<li>Navigate to a sufficiently windy place. A place that measures 5 or more on the WindScale is sufficient for the purpose of this task.</li>
</ul>
<prereq>

<context>
<note outputclass="caution">Following the steps listed below might make you lose your possessions including, but not limited to, your umbrella.</note>
</context>

<steps>
<step><cmd>Stand on firm ground and open your umbrella.</cmd></step>
<step><cmd>Watch your umbrella fly away. Simultaneously, sing at the top of your voice <userinput>Chhatri udi, ud ke chali</userinput></cmd></step>
</steps>

<postreq>Acquire a new umbrella.</postreq>
</taskbody>

<related-links>
<link><linktext>http://writing-technical.blogspot.com/2010/01/quick-and-rude-guide-to-dita-part-1.html</linktext></link>
<link><linktext>http://writing-technical.blogspot.com/2010/01/quick-and-rude-guide-to-dita-part-2.html</linktext></link>
</related-links>

<task>

 

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.