Thursday, September 23, 2010

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.

Wednesday, September 8, 2010

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.]

Saturday, September 4, 2010

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.