Daily Recap

The barbaric act of Hartal was enacted by Marxist-led political parties in my home state of Kerala, in the name of protest against high food prices.

The Word MVPs site I frequent regularly has an interesting and long article on Conditional Cross-Reference Labels for Numbered Headings, while PowerPoint earned some flak from the US military. Alternet ran an excellent article on the deleterious impacts of industrial agriculture on the environment and Bangalore daily Deccan Herald published a dubious article supporting GE crops. It was refreshing to read about the rise of new generation of British poets (I am currently reading poet laureate Carol Ann Duffy's poems anyway) and an interview with well-known science fiction author Ray Bradbury, who has never been to college. Noted defence analyst K Subramanyam writes on Communication intelligence in the backdrop of the phone tapping allegations by opposition politicians in India.

Usage of And/Or

The debate on whether "and/or" is correct or not refuses to die down. It was pleasing to see an entry on 'and/or" in the Chicago Manual of Style FAQ site (Look at the March Q&A section).

In the March Q&A, CMOS says, "...and/or “can often be replaced by and or or with no loss in meaning." For multiple choices, CMOS says use or . . . or both .

Despite knowing this, we make mistakes, right?

Phenomenons or Phenomena?

What is the plural form of phenomenon? School kids will tell it is phenomena. But what happened to "phenomena" in this newspaper report?

Pachauri said: "Given the variations in the ocean currents, wind patterns and related sedimentation as well as other phenomenons related to the weather..."

The news report also has other usage issues. "The six-member Pachauri Committee, tasked to examine the possibility of cutting a canal through land mass between Dhanuskodi and Rameshwaram,..."

Tasked to? When Task is used as a a verb, 'with' follows it. It can be "tasked with" and not "tasked to".

The third paragraph has a spelling mistake in "environemntally", that too on World Earth Day!

Technical Writing and 5Ws' and one H

Can the legendary 5 Ws' and one H, widely used in journalism, applicable to technical writing as well? I had this doubt after I viewed a presentation titled, How to Write.

Let us look what 5 W's and One in journalism. It means:
Who?
What?
When?
Where?
Why?
How?

Does who, when, and where matter for a scenario where a user is operating a software? I have my doubts. Anyway, this is an interesting point and I will keep it in my mind whether 5Ws' and One H can indeed be a guideline for technical writing.

In journalis, the inverted pyramid style evolved due to space constraints in a newspaper. For a newspaper, space is a very important thing, because ads occupy some amount of space in a newspaper page. Moreover, the technique was also useful to readers who want to get all the necessary information by reading the first paragraph or lead. It is difficult to apply the same in the strictest sense to a user manual. While space is finite in a newspaper, it is not so for a user manual. Page design also does not limit how much and what you can put in a user manual page.

Journalism is called the first draft of history. A user manual is not a first draft of history. The content in a technical document is always restricted by the product it documents, and it is always meant for specific or multiple audiences. Unlike journalism, where the topics are varied, a user manual is somewhat restricted in what it can document.

The level of precision required in a technical document is very high, compared to newspapers. Newspapers deal with facts, that can turn wrong later, because News is supplied by human sources with a specific personal intent. Such news can be true or it can turn out to be false later. SMEs in a software company do not have a personal choice in providing information. What they provide or what the technical writers learn should be precise information.

In most companies, technical documents get written based on approved structure and style. The writing is always restricted by a style guide that effectively prescribes the Do's and Dont's. In journalism, there is considerable freedom to write in a style that suits the writer. In fact, media houses do have a style guide, but features provide the journalist to adopt a free style in their writings.

Lastly, technical docs are meant for users to complete a particular task. They are not meant to entertain anybody. Moreover, the news published is governed by values such as proximity and significance.

The challenge in technical writing is to convert complex technical concepts to simple information readable by any kind of user. This is a unique challenge that requires considerable self-study, analysis, and judgement. Writing a front-page story is not that similar to writing complete procedures that can reduce support calls.

Terms for Technical Writers

Agile Development: Software development based on an iterative and incremental approach. Regular feedback and frequent changes effected to plans to develop a software. See Agile Manifesto for more.

API: Short for Application Programming Interface. According to Webopedia, An API is a set of routines, protocols, and tools for developing software products.

Application Server: A software (set up in a centralised location) used in intranet/internet environment to query databases or for business processing.

Batch Process: A process that runs a series of commands or processes.

Build: Generally, a pre-release version of a software program. There will be many builds that will be tested before the final product is shipped to the customer.

Burndown chart: In Agile software development, this chart tracks sprint progress so that project managers can decide which items must be removed from the sprint backlog and moved to the next sprint.

CSV File: Short for Comma Separated Value file, which is a file format used to exchange data between different applications.

Design Spec: A technical document that contains descriptions of the design of a particular product.

DITA: Short for Darwin Information Typing Architecture, an XML-based architecture for authoring, producing, and delivering technical information.

Eclispe: Eclipse is an open source and free development environment.

Exception: In Java, exception refers to an object that describes an error condition in the code.

Flat File: A text file or database that contains unrelated records.

Iteration: In Agile software development, a short period of time (varies from two weeks to a month) in which the development team develops a complete feature or functionality.

JDK: Short for Java Development Kit. A Java Development Kit (JDK) is an environment for creating Java applets and applications.

Run book: A reference document, generally used by system administrators, containing procedures to begin, stop, and supervise a system or network.

Single Sourcing: A documentation approach used to create multiple documents from a single content source or library.

Six Sigma: A data driven system to continuously build and improve quality into processes and products developed.

SOA: Short for Service Oriented Architecture.

SOP: Short for standard operating procedures. A document that contains the standrad operating procedures to run a system efficiently.

Table: In a relational database, a Table is a set of columns that contain data.

Test Case: A document that lists inputs, actions, events and the results expected from a working software build. This is used to test the functionality or feature developed by the software development team.

Test Plan: A plan that details the approach to test a software as a whole, and not the parts.

Topic-based Authoring: A content creation approach that creates stand-alone content, which can be easily reused in any context, managed, and assembled.

Use Case: A document that describes how a type of user uses a sofware to achieve a particular goal or goals.

Software Design Document: A document describing a software or an overview of the architecture of the software. There are two kinds of design documents: High Level Design Document (HLDD) and Low Level Design Document (LLDD).

XML: Short for Extensible Markup Language, a markup language.

Bad Day for Indian Space Research

It was sad to read that India's efforts to launch the Geosynchronous Satellite Launch Vehicle(GSLV D-3), powered by indigenously developed cryogenic engine, failed to succeed. Read the report in the Times of India.

List of Celebrities

The following minds do not find space in newspapers and magazines published in India:

Agnes Heller - Hungarian philosopher

Héctor Abad Faciolince-Colombian novelist, essayist, journalist, and editor. He has studied Medicine, Journalism, and Philosophy.

Claire Denis, the well-known French film director.

Uladzimir Arlou becomes first laureate of “European Poet of Freedom” award.

French philosopher Elisabeth Badinter

Geert Lovink-media theorist, net critic and activist.

Javier Cercas, writer and Professor of Spanish literature.

Rosa Montero is an award-winning journalist and author of contemporary fiction.

Manuel Rivas is a Galician writer, poet and journalist, and founding member of Greenpeace Spain.

Michal Hvorecky is a Slovak author and winner of many prestigious awards.

Robert Pinsky is a well-known American poet, and the poetry editor at Slate.

Krzysztof Varga -Polish writer and journalist.

Jonathan Safran Foer is an American author best known for his novels Everything Is Illuminated.

Edward Hirsch, American poet, has writteb a book, How to read a poem: and fall in love with poetry.

Barbara Ras is an american poet.

Colm Tóibín-award-winning Irish novelist and critic.

The Word Hurt Locker

Hurt Locker means a state of intense physical or mental pain, says the MacMillan dictionary.

Hurt Locker won the Best Movie Oscar this year.