Also see Technical Writing Resources

Gary Conroy’s Site

By Sita Chandrakant Bhatt

One of the most important challenges that a technical communicator faces, is the comprehensive and concise presentation of information. This gets even more formidable when the medium is a website for a broad spectrum of topics. I have seen several websites with useful and exhaustive information, but their tedious presentation failed to draw quick browsing audiences. So, I was pleasantly surprised when I turned to the oft-recommended Gary Conroy site. It was interesting to observe that the site is broad and comprehensive in its scope, yet concise and compact in its presentation.

A well-designed home page welcomes you to the site, with links to Current News/Articles, Web Links and Forums. The links on the home page display only the latest in current news, articles, web links and forum discussions – a very useful feature for time-pressed professionals. The names of new subscribers to the forum are displayed on the index page, providing a personal touch.

The Current News and Articles feature topics ranging from Planning, Document Structure and Techniques to Editing, Cost and Resource Management. The topic that caught my eye was XML - a much-discussed subject recently on a popular forum for Indian technical communicators. Delving deeper into the XML section led to an outdated, but extremely interesting article called An Introduction to XML. There were other links alongside the article to give me a broader understanding of the subject. This feature deserves appreciation, as most websites may not display links to other sites for fear of losing the viewer, (which is quite an obsolete concept anyway).

Most interesting was the fact that some articles on the Gary Conroy site carry links to articles with a contrary viewpoint. Thus, the reader is enabled to see both sides of the coin and form an independent, unbiased opinion. For example, the article “Stop it with those 50-Step Procedures” advocates the use of a maximum of 9 steps in a procedure. This article also links to a counter-article, which supports the opposite view. The reader is free to decide if the theory holds good or not.

The Web Links section presents links to resources on the Internet – an exhaustive collection with areas of interest for the beginner, intermediate and power user. Beginners could pick up writing skills by looking up the links to Introductory Techniques and References, Real Life Stories and Tools. There is a section that provides links to humorous articles on the web - all related to technical writing – quite a respite for any professional.

The Forums link takes you to the Forum index where the latest posts are displayed. To answer a query or to comment, you have to register as a member. Registration is free. Registered members have access to customize posting news and comments, select how many news items to show on the homepage, select different themes and other such account preferences.

The dark blue background with black fonts made reading difficult. I had also assumed that the images used on the index page were linked hotspots – they were not.  By website design standards, this is a waste of valuable space.

Nevertheless, the overall presentation, and most importantly, the high-value content makes the Gary Conroy site a definite bookmark for the technical communicator. A valuable takeaway for the technical communicator, or any other professional, would be to understand how to optimize on space – a precious commodity whether in print or online – and yet present the most comprehensive information.

(Sita Chandrakant Bhatt is a Senior Technical Communicator, Infosys, Bangalore You can contact her at sitabhatt@yahoo.com)

Resources for Technical Writing

By Tharoor Gopalakrishnan

Development Process: Writing / Website/Software

www.cdtinc.com

Understanding the phases of the Software Development Life Cycle (SDLC) and the deliverables at the end of each phase becomes a key priority for Technical Writers. This site lists the documents across the ADDEI phases viz., Analysis -> Design - > Development -> Evaluation -> Implementation for

• Technical Writing Process

• Web Development Process

• Online Help Development Process

• Computer-Based Training Process

• Instructional Systems Design Process

• Accelerated Learning Process

Documentation Techniques

http://developer.apple.com/technotes/tn/tn1047.html

Writing for the web is an art. It requires discipline and tact to keep writing short and sweet. This tech note outlines various facets of creating web-friendly documentation. “If it were not for the N^th  hour then no documentation would be done.”

Writing for an American audience

http://www.dartmouth.edu/~compose/student/special/esl.html#essay

The Communication Center of Dartmouth College maintains this link. A fundamental principle when writing for an American audience is: “Your essay should model itself on an arrow: straight, sharp, and swift. It should not zigzag; it should not move in circles.”

Documentation Resources http://cohesion.it.swin.edu.au/teamb/documentation/index.shtml

A one-stop link list for a plethora of Technical Writing Resources. The PDF downloads are worth the visit.

Estimating Documentation Effort

www.stc.org/intercom/PDFs/2001/200111_08-11.pdf

www.public.iastate.edu/~honeyl/417x/pdf/smith.pdf

An oft-repeated question on TWIN. Precious effort that does not go recorded is “Effort spent on Documentation”. A lot of effort is spent searching for information on this subject, only to realize that the first link takes you to a PDF on the subject by our own Makrarand Pandit.

The second link elaborates formats that can be fine-tuned to suit our requirements. David Smith has put in excellent formats that allow us to capture the time spent on Documentation.

Documentation as an art

http://www.mala.bc.ca/~soules/eng315/textbook/mullis.htm

This page takes you through certain subtle nuances that perfect the art of documentation.

Information Design

http://saulcarliner.home.att.net/id/processresources.htm

Information Design has lately generated a lot of interest in technical communication circles. Saul Carliner, who was the keynote presenter at the last Annual meeting of the STC, India Chapter, is an authority on the subject.

What’s the right word?

http://www.rbs0.com/tw.htm

Several questions have been raised on this subject. Options have been presented and suggestions sought.

The next time around, before you start typing your subject line: “Right usage 1 or i)”, I suggest take a detour. Go through the contents available here.

Paper Vs Online Documentation

http://www.techscribe.co.uk/techw/paper_v_online.htm#typical_online_documentation

This site has been around ever since DTP and online text formats changed how information is shared. This debate is further supported by related links on “Cost of paper and online documentation” and “Cost of bad documentation”

(Tharoor Gopalakrishnan is a Technical writer working with Polaris Software Lab Limited. You can contact him at tharoorg@fastmail.fm)

STC India | Home | Contact Us

Copyright © 2003 India Chapter STC. All rights reserved.