– Sharada Palagummi
I am a technical writer and of course, I deal with technical content. I want to create great documentation. I know that technical knowledge and language skills are important, but I also want to use state-of the-art methodologies and authoring tools. However, my company does not find it financially advisable to invest in them.
I sighed in despair whenever I heard all those words like DITA, Author-it, Documentum, WebWorks, single-sourcing, structured authoring and so on. Oh, what a shame, I did not even work with FrameMaker and had never even seen SnagIT.
Whenever I read or heard about the latest tools or methodologies, I was all eyes and ears; wishing that I could be using them. Friends suggested jumping, but I was quite happy with my company: my role and my work and, yes, my package too.
One day, while watching a movie, I suddenly told myself, “Don’t whine; THINK.” Then, I did something that changed my outlook.
No more did Epic Editor bring epic images in front of my eyes; Benhur and Ten Commandments stopped bothering me. I stopped imaging DITA as dominant and recessive genes (of course, though Darwin himself did not know much about genetics) and in the Mentos ad. I did not feel stupid when I heard all the buzz words.
This is what I did…
I started reading about DITA, Author-it, DocBook, Documentum, single sourcing, structured authoring, information mapping and so on in detail. I tried to apply the knowledge to my scenarios.
For example, when I read about DITA, I read about specialization and inheritance, information typing, and architecture. I concentrated on information typing; I opened a couple of recent user manuals we developed and associated terms such as concept, task, reference, message and typed phrase with the text in the manuals. I understood the nuances of semantics of topics and semantics of content.
I opened my dictionary and looked up specialize and inherit. The meanings “adapt or set apart (an organ or part) to serve a special function or to suit a particular way of life” in the context of biology and “derive (a quality, characteristic, or predisposition) genetically from one’s parents or ancestors” in the context of genetics helped me to understand what DITA is trying to do.
I read about the way Author-it stores all information as objects in a central database, giving authors the ability to combine and reuse objects in various ways.
Similarly, I tried to associate all the theoretical concepts with what is happening around me.
I set about typing the information, identifying the information that could be inherited, and identifying the structure and content that could be adapted. I made the following preparations:
- Structure
- Planned a structure for each user document type (installation guide, user manual, programmers’ reference manual etc.) we generally prepare.
Here, I remembered that most user documentation, these days, is accessed online (Apparently, DITA does not encourage the book as a basic structure!).
A user looks up a document for a specific problem and does not want to wade through information about all the hundred marvellous things the product does or how to do them.
A user wants to quickly know how to do a task without being expected to have read all the previous topics in the document – manual, help whatever.
- Represented the structures pictorially using colour codes to indicate optional and mandatory items.
- Printed an A4 size poster for each type of document depicting the recommended structure.
- Presentation
- Created document templates for each type of document.
- Specified styles for different types of element; created a few and modified a few others wherever I needed and I could.
- Information Typing
- Identified the six most often used information types
- For each type, listed the style to be used, the item it is supposed to succeed, one or two rules to remember while using it.
- Created an A3 size poster representing the above data in a table.
- Reuse
- Identified the content that can be reused across all the products of the company and for specific products. Apart from content such as copyright information and document conventions, identified parts such as topics about the product that are not likely to change for quite some time, table of shortcut keys, and table of common menu options such as File, View and Edit.
- Saved each reusable part of the content in a separate file.
- Created an index for reusable content with the name of the file, location of the file and description of the content.
- Access
Made all this information available on our documentation server.
This helped in improving our efficiency in documentation significantly.
I realised it might still not the same as having a tool to impose structure, reuse and consistency, and help in many other ways, and I need to look for tools.
Microsoft’s HTML Help Workshop is free. Yes, it is really free; no strings attached. It is compatible with HTML files created in any other application and it has a nifty decompiling tool, which produces source HTML files and images from a compiled CHM file. We have been using it for decades.
I started looking for open source software, found an unbelievably large number of them and tried out quite a few of them.
Nvu, GIMP, DoctoHelp, WordWeb and many others are robust applications. Eclipse is an integrated documentation development environment. There is an open source DITA authoring platform and DocBook is available as open source software.
There is plenty of scope to do a lot of things with the open source software and a few housekeeping operations.
I have a nice pin-up and am trying to drive a nail into my door. Alas! I don’t have that beautiful, fashionable electric drill everybody seems to have. I do not use my well-manicured nail to make a hole, ugh! But, I settle for a hammer…
References:
http://xml.coverpages.org/DITA-technologyreview.pdf
http://wiki.eclipse.org/Authoring_Eclipse_Help_Using_DocBook
http://www.indoition.com/online-help-authoring-tools-survey.htm
http://www.eclipse.org/articles/article.php?file=Article-Authoring-With-Eclipse/index.html
About the author:
Sharada Palagummi works with Integra Micro Systems. She has more than 23 years of experience in technical writing, localization and teaching Statistics to undergraduates. She has done courses in French, Italian, Japanese and Chinese. You can contact her at sharada.kalapatapu@gmail.com.
About the illustration:
Used with permission from Anagha Chandratrey.
I really like this article because it says:
(i) Don’t whine. Roll up your sleeves and Do.
(ii) Understand WHY you are doing something and ONLY THEN find the way (tool) to do it.
(iii) Just because you have a drill, every inch on the wall does not need a hole, thank you.
I enjoyed reading every line of your article. One of THE BEST Articles that I Have EVER Read! I liked the way you have ended it too 🙂
Thank your Sharada!
It’s a nice piece of writing. Most of us get fascinated with the Technical Writing tools not being much aware of what are the pro’s and con’s of those tools. I liked the way you shared your experience and signaled all writers to first browse about the fascinating tool to know the purpose of the tool.
I liked the approach Sharada has taken to know about new tools and using the concepts to suit her needs. the article is very well written and easy to understand. Thanks a lot Sharada.
A very well presented article. I enjoyed reading it.