DITA Authoring – Is it really expensive?

DITA has been the buzzword for 5+ years. The biggest advantage of DITA is content reuse. You write the content only once and reuse it across multiple topics. Reusing a complete topic is also possible. Big software organizations have already taken the lead in implementing DITA for their authoring needs. Everyone seems to be using DITA for creating pdfs, word docs, and online helps. DITA looks simple, just a collection of concept, task, and reference topics. However, for small and mid-size companies, its implementation becomes troublesome not because of technical complexities but because of costs. The technical writers (managers included) in such companies feel that the tools to implement DITA are expensive. At the time of writing this, XMetal was available for $695. Arbortext Editor was not cheap; it came at a same price. So they are still using Microsoft Word (or should I say Microsoft Word 2003 :))

However, nothing can stop the technical writers in these companies from joining the DITA bandwagon. You will be able to implement DITA at very low cost if you seek active involvement from engineering. Before I tell you how, please understand that internally every DITA authoring tool uses XML or Extensible Markup Language. So you just need to have an intermediate level understanding of XML. Rest you can leave to the developers.

XMetal, as stated above, is pricey. There’s no need to buy that. Start with a text editor. You can start with Notepad++.  The advantage over Notepad is that it shows  textual elements in different colors.

There are five things which you need to come up with a DITA deliverable. These are DTD, XSL, dita files, ditamap, and the conversion from ditamap to pdf ulility. DTD defines the structure of your topics. XSL defines the formatting of text and placement of elements. Creating DTD and XSL requires expertise in XML. You can leave that to engineering

The technical writing team starts by first drawing the structure on a piece of paper. Thee team then agree on the formatting. Both the structure and the agreed upon formatting information is then passed on to engineering to create a DTD and an XSL.

Engineering work is over. Now it’s your turn to create topics. Open Notepad++ and use known HTML tags to write content. For example, use <p> tag for paragraphs and <ul> tag for lists. You just have to include an XML declaration. That’s the only XML thing you need.  Be sure that you save your topic as xml and not html file. Create all your topics in Notepad++ this way. The next task is to create a ditamap so that the topics can be hierarchically arranged. Ditamap is nothing but a TOC with links to individual topics. You can also create a ditamap in Notepad++. Just enter the references to the individual XML files making sure that no XML file is missed. Save it as ditamap file. The last task is to convert ditamap to pdf. You can also do this for free by downloading the DITA Open Toolkit. Specify the format in which you convert to pdf. Apart from pdf, you also get the option of converting to Webhelp and chm.

This free implementation will be cumbersome when you take the first shot. But over time you will get used to it and become more productive. Think of the team effort you will save with DITA reuse.


The beauty of agile user documentation

Writing user guides and admin guides used to be a time-pass activity during 75% of the SDLC. All the developers used to be busy in coding. There used to be no UI with nothing to see. All the efforts were directed toward building the application rather than writing some stuff. Technical writers were never calling in meeting and training rooms. However, the latter 25% used to be the most troublesome for technical writers. In this period, all the developers used to claim the honeymoon period. The technical writers have no clue of who is working on which part and used to make rounds from dev A to dev Z and back. Technical writers have to make their own assumptions and deliver on time with close to 100% quality expectations. However, once the documents entered the SME review stage, usually after the release, technical writers used to face a severe reprimand for no fault of theirs. People used to shout that the guides are not technically accurate.

All this is changing with the rapid introduction of Agile model. The beauty of Agile lies in daily meetings or scrum as they are called in Agile parlance.  In this blog post, I am going to give a first-person experience. The technical writer sits along with developers and QAs in these scrum meetings. I make it a point to attend all the meetings. At the start of the meeting, I know what the requirements are, which ones have been fulfilled, which are in-progress, and which will be moved to next release. As a result, I am able to create an excel sheet of requirements and track them using different colors. When the developers tell about their tasks, I get to know who is working on which functionality. So I am easily able to map the requirement to the requirement owner. This person becomes my point of contact. As a result, I am able to categorize my points of contacts according to functionality. I do not have queries for the people who are co-located, but I do have few for people working in the U.S. I try my best to get my queries resolved in these scrum. Product management, which is not a highly technical function similar to technical writer, extends full support to me. If I am not getting the inputs, they get it for me through their channels.

Whenever I complete a significant portion of the guide, I send it out for review. Sometimes, I do not get any review comments. However, they always know that I am working in tandem with them. I do not encourage 1:1 verbal review comments. However, I am okay if these comments are given in a group. Nothing brings more joy when dev managers sometimes provides information to include in a guide.They value documentation!

Sometimes, they say that they already have a guide. However, they want me to write it according to technical writing principles and word usage. That also brings happiness. They know my worth!

Agile is definitely not the best thing to happen for documentation. There are still some gaps. However, for a technical writer like me, it is definitely better than SDLC.

Needed a new edition of MSTP

If you are a technical writer and someone says “style guide”, the first thing that often strikes the mind is MSTP. True there are 10+ other style guides and counting, but writers MSTP.

  1. The best thing about MSTP is that it is available for free, though not from Microsoft. If you google, you will find a number of links from which you can download pdf. Earlier, Microsoft was also providing chm for download. These chms have been passed onto generations of technical writers, absolutely free. Yes! If you do not have one, ask your friend to send it across. Chicago Manual of Style, Elements of Style, and Read Me First style guides come for a price.
  2. MSTP has been in existence for more than 15 years. In fact, the first version published in 1995 was the only technical writing style guide available. No matter the number of grudges people hold toward Microsoft, the reality is that these same people don’t want to move away from Microsoft products.
  3. MSTP is quite exhaustive. Containing 13 chapters, it covers everything from Legal Content and Front Matter, Tone and Rhetoric, Grammar, Punctuation, GUI documentation, Web content, Formatting, Style Issues to Indexing. It is an all-in-one reference.Chicagodoes not have anything on GUI documentation while Apple Publications Style Guide has nothing on grammar.

Like all other technical writers, I also prefer MSTP. However, after the last release of MSTP in 2005, there has been no new release. Technology has changed rapidly and with it the perception of users toward documentation has also changed. Therefore, I would like Microsoft to come up with a new version of MSTP so that it retains its numero uno position for many years to come.

Below are some of the things that I would like to see in new release of MSTP:

  1. A chapter on documenting mobile interfaces. A large number of IT organizations are developing applications for both mobile phones and desktop computers. Mobile phones have altogether a different set of controls and thus require a separate chapter.
  2. Additions in Documenting the User Interface chapter. The applications of today do not have only toolbars and menu bars but also panels and ribbons in abundance.
  3. Modifications in Punctuations chapter. Now the trend is on avoiding punctuations as far as possible. Punctuations tend to distract the user and hinder readability. Gen Y likes to read “e-mail” as “email” and “Web site” as “website”.
  4. Additions in Grammar chapter. There is ample scope for including content on adverbs, conjunctions, and sentence constructions.
  5. A chapter on Graphics. A majority of writers use graphics as visual aids. This chapter could contain information such as graphic file, color formats, alignment, sizing, and sampling.

Creating PDF for Free

One question that almost every information worker asks is:

I have an important document that I want to ship. How to make a PDF out of it so that it is compatible on all platforms?

For the majority, the answer is Acrobat Professional. At first thought, Acrobat Professional seems like free software similar to Acrobat Reader. However, when they go the software download site, they find it to be very expensive. Therefore, they say, “Let’s skip creating the pdf and ship the documents as is.” All recipients do not have the source software or have different versions. As a result, the document does not correctly open. This leads to lot of to and fro communication and eventually loss of goodwill and trust.

In today’s era of cloud computing and hosted software, some smart users have found a free of cost method to create a pdf. There are many Web sites on which you can attach your source document and click the Create PDF button. You get the pdf through a URL or as an attachment in your email account.

However, there are some big disadvantages of this method:

  1. These online PDF creation sites usually generate a zip fie. You need to spend extra time extracting the pdf from zip.
  2. You do not get any assurance of security and privacy. The submitted document gets stored on the external Web server. There is a high chance of a hacker reading or manipulating your document. Your organization may not allow uploading of company documents on external Websites.
  3. These Websites do not accept large documents. Usually there is a cap of 2 MB. Therefore, creating pdfs out of large documents, such as those containing tables, images, and diagrams, is not possible.

Thus the above free pdf creation method does not work for all documents. What is the ideal solution then?

Well, if you do a Google search intelligently, you will come across many free pdf creation software. Yes! You read it right. These are free for life. The best thing is that the installer is less than 10 MB. You can download and install the freeware in few minutes while it takes a substantial time to download Acrobat Professional.

Examples of free PDF creators:

  • PrimoPDF
  • Solid PDF Creator
  • PDFill PDF Tools
  • Cool PDF Reader
  • Doc-Docx to Pdf Converter 3000

Some of these also offer a toolbar button to generate pdf in one click. The source documents and resultant pdfs reside on your hard disk only. The best thing is that there is no limitation of file size. So, the next time you need a pdf instantly without comprising security, google and download a freeware.

Search Engine for Home

Hey, how many times you open Google.com during a day? Your answer is not going to be less than 10, right?

Search engine, such as Google.com, is like a prompt waiter who accepts your order for searching any information available online and serves the results on your desktop. The beauty of Google is that we get the results instantly. We do not have to call up any person and listen to their rants for bothering them. In fact, with Google, we need not remember any other URL. Google is intelligent; it keeps on updating its index and always serves the fresh information. Google ensures that we never lose any information available online.

Now how many times you forget an item that you kept somewhere at home? Let’s say you always keep all your important documents inside a file in your locker. Now, one fine evening, you return to your house after making a follow up visit to the doctor. You are holding the prescription in your hand while your partner is making scary faces. She is angry because you are late for the weekend outing. So, instead of spending time on opening your trusted locker, you hurriedly slide the prescription inside a large book on your study table. You firmly believe that you are going to remember that folly. Days pass and you keep on forgetting. Two weeks later, after dressing up for the next follow up visit, you open the file in your locker to take out the prescription. However, the locker is there; the file is there; all other important documents are there; but the prescription is nowhere. You scratch your head. Where’s that damn prescription? You keep searching for days while your family members taunt you for being careless.

You are not alone. Billions of people in this world face the same situation day and night.

What then is a solution to say bye to such woes?

It is sad that most researchers are not thinking about solving this problem.

Radio Tagging: One solution that I propose is radio tags. To start with, you need to draw a detailed digital map of your home. You can start from scratch or convert the old architectural blueprint to its digital equivalent. Be sure that you do not leave even an inch. Then attach a clip size radio tag to every item in your home. The radio tag, in addition, in addition to the item name, short description, detailed description, date, size, and weight etc., stores the exact map coordinates. Use these coordinates to zero in the exact location of the item you forgot. Next, install miniature size radio antennas in every room. You already have a computer at home, yes!

The radio tags continuously reflect the radio waves transmitted by antennas. So, whenever you move the item, say a prescription, the radio tags reflect the new coordinates. This information moves to your computer, and you have the updated location. Please note that this process does not require any intervention on your part. It is different from creating an xls file or other spreadsheet and then manually adding or updating the data. This gives you the luxury of a search engine for keeping track of every household item. Of course, radio tagging is expensive. Apart from equipment, you need technical experts for installation and servicing.

I hope that our researchers will bring some innovation to bring down the price of this extremely user-friendly technology.

Image Editing Tip – Why IrfanView and Not Any Other Tool

Many screen capturing tools, in addition to screen capture, provide image editing features. However, most of these tools are expensive and their image editor is too difficult to work with. IrfanView does not have all screen capture options. However, it does have an easy-to-master image editor.

Based on my experience, I have listed the top reasons for considering only IrfanView and not any other tool:

1. IrfanView is a freeware in true essence. Other freeware periodically prompt you to install a premium version of the freeware which costs you a lot. They say that the expensive one has complete set of features. IrfanView does not have any premium sort of thing. You won’t at any time get to see annoying prompts.

2. IrfanView is ultra light. The installer is less than 2 MB. You can download it from multiple mirror sites.

3. The beauty of IrfanView lies in its simplicity. Yes, the interface is simple. There is only one menu and one toolbar. There are no floating panels or pods thus providing plenty of space for your hard-earned images.

4. While the beauty lies in the interface, the magic lies in usability. You just need to select one file from the Images folder. IrfanView has done away with boring rectangular selection tools. You just click a point on the image and drag to select. After done with editing one image, press S to save your image as another file or in different format. Note that you also get a shortcut for Save As. You rarely find shortcut for Save As in other software. IrfanView takes special care of navigation. Press Space to move to next image and Backspace to move back. Press Del to delete an image. Note that you are not using any combination keys such as Ctrl, Shift, or Alt.

5. IrfanView lets you specify the quality level and appropriate format for your image. There are more than 15 formats to choose from. You can specify progressive for JPEGs, interlacing for GIFs, transparency for PNGs, and compression method for TIFs. You can even create a multi-page TIF.

6. IrfanView has sufficient number of color corrections and image enhancement options. Without spending a dime, you also get Red Eye removal. For enhancing your image, you get 3D Button, Sepia, Pixelize, Emboss, Blur, Noise, Pixelate, Relief, Twirl, and much more.

Apart from the above image editing features, IrfanView has a fair number of screen capture options. The options include full desktop on multiple computers, foreground window, region capture, and object capture. As in other screen capture software, you can specify hotkeys and timer delay.

If you were to aggregate the image editing and screen capturing features of IrfanView, I believe that you will like only IrfanView and not any other tool.