The Golden 80s

Jobs like journalism and technical writing require employers to assess a candidate's writing skills. While CVs and covering letters can be written by someone else, an on-the-spot test will definitely reveal the real writing skills of a candidate. So, you go to an interview, and you are asked to write a test. The test will mostly consist of a few stupid grammar questions, followed by a question to write an essay, or rewrite a passage. The biggest issue with such an approach is my poor handwriting. I do still keep notes, but the amount of writing done is pretty less. After a few minutes into the test, I really struggle to keep the words getting bigger and bigger on the answer sheet. Towards the end of the test, it gets really bad, with the letters getting bigger and fatter, and more sheets of paper required to completing the test. In IT, innovation is the buzzword (Since I am writing a blog post, I am not expanding the abbreviation as per the guidelines in innumerable style gui...

Analytics is the buzzword now and technical communicators cannot stay away from that either. There is a really interesting discussion going on at the "Users of MadCap Flare" group at Linkedin. The discussion is centered around how Google Analytics can be implemented in a Flare HTML 5.0 project. It is a good discussion and is pretty useful. Please have a check.

If you have read official documents released by the central government or the state governments in India, you will know the pain. The writing in such documents is characterised by ambiguos, lengthy, and wordy sentences. " Officialese " is the name given to such kind of writing. The same applies to legal documents also. Now, the US government has decided to do something about obscure writing. The Plain Writing Act of 2010 seeks to etsbalish that "Government documents issued to the public must be written clearly, and for other purposes." Interestingly, the act defines "plain writing" as "writing that is clear, concise, well-organized, and follows other best practices appropriate to the subject or field and intended audience." So, plain writing gets legal approval. Technical writers beware!

As technical writers, most of us get a chance to review documents prepared by colleagues or writers from other teams. While a few may be reluctant to do reviews, it is a fact that the reviews provide technical writers with an opportunity to participate in the quality control process of user and technical documentation. If the team has a technical editor, he or she may be left with enough time to do a thorough review of documents. A process will be in place to plan and complete editing. If one of the team members take up the taks of editing, the edits mostly will be a mix of “copy-editing” and “technical editing". A“production edit” can also be done on the draft versions of the PDFs created to ensure that everything is all right before it is send to the customer. The limiting factor indeed is time. The first step in editing is to read the entire document once. It is indeed a quick read just to get an idea of what is it all about. Such a reading does give me a...

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?

Here's a new screencasting tool: http://www.screenpresso.com/index.html. For Windows XP users, Microsoft.Net Framework is required.

The blogging world is abuzz with the rising popularity of social media and the way it's gonna change documentation. Microblogging sites such as Twitter and networking sites such as Facebook are expected to change documentation in a revolutionary manner. There are predictions galore about the impending demise of printed manuals and the inevitable replacement of them with blogs, wikis, and social media (I feel this a very narrow view of how documentation would evolve/ Let us wait and see). Remember Naipaul when he said that the novel is dead. How useful is social media to technical writers in India? I feel it is a depressing zero. Most companies in Indian restrict access to sites such as Twitter during work hours. Certain companies even block access to webmail and prevents installation of chat software. Others even go to extent of blocking internet access during work hours, ostensibly to increase productivity. In others, even blogs and forums, which I think are more useful to tech...

The world's smallest deer discovered in the Himalayas, says AP . "I do not like to track metrics like the number of comments as a quality measure. Anything you track is likely to cause some change in behavior," says Richard L. Hamilton, author of Managing Writers: A Real World Guide to Managing Technical Documentation, in an interview . He also says that DocBook is used more than DITA. Interesting. What kinds of documents do Agile software development require? Read this blog post by Eelco Gravendeel. Making a strong case to let sci-fi movie classics to remain as classics is the article, Top 10 Sci-fi movies that should never be remade 2.6 million viewers tuned in to the final episode of the most recent series of Ladette to Lady , a TV serial that is related to reviving the debate, Why can't a woman be more like a lady? Interview with Ian Rankin , one of my favourite crime fiction writers. Oxford University faces flak over land use. Oxford University dragged into ...

"Without interacting with the user, you can’t learn the user’s vocabulary and the tasks they need to perform. Without a knowledge of user vocabulary and tasks, your help material is destined to be unhelpful. Without helpful user assistance, your role on the project team and your own sense of importance on the project diminish." I have pasted these words from Tom Johsnon's excellent post on the various level of harassment and stumbling blocks encountered by the hapless technical writers. Another method of ostacrization is "the domain is so vast" or "the functionality is too complex" comments. This is equivalent to telling you that I am not share my knowledge that easily with you.

When I told my journalist friends that I would be joining a software firm as a technical writer, a few raised their eyebrows. While a couple of them said this was a good move, others were less optimistic and predicted that I would soon regret that decision. While I have not started to regret that decision in a very bad way, there are things I enjoy in technical writing. The most important thing I like is the attention to detail. As a technical writer, I have to measure each and every word, each and every sentence, each and every paragraph, and each and every punctuation mark I insert. Every word I write is dear to me and I don't want people to misread it. I also realised that continuos and constant rewriting improve my deliverable in whatever format the team wants. Rewriting is not a boring task, but it is an interesting task. For others, writing is all about writing something new. They don't understand that if they properly rewrite their own writing, it will look new. It shoul...

In India, the use of 'you' in the vernacular languages is very dangerous. 'You' is a sign of bad manners and the speaker will receive a sound thrashing from the elders. The harmless second person pronoun is a sign of disrespect and challenge to authority. In Indian households, 'you' is reserved for the patriarch, and a strict no-no for children. Mind your words; you means insulting somebody. For user manuals, Indian patriarchy has no place and 'you' is a perfectly right word to use. 'He' or 'she' invites comments on gender bias and sexist language and has no place in the manuals. Technical writers cannot use 'Dear Sir' or 'Dear Madam' to address the reader. Nor can they use words like 'Boss' or 'Guru', words that produce a dramatic effect on the sons of the soil in Bangalore. A user manual will be read by single reader, and a single reader only. This is unlike the scene in Indian trains where bored passenge...

I was reading Keith Solty's blog for a few days. I realised that if you are following a blogger, you should read the posts right from the start. By doing this, you will get a better sense of the person, topics, interests, and so on. It is easier to connect with the blogger if you follow the blog from the start. I did find Keith's posts very informative.

I was working with lots of tables last week. Information scattered on many pages was rearranged and put on tables for more clarity. Because I was focusing on tables for most part of last week, I decided to dig a bit about tables and their structure. Broadly, there are two types of tables: Formal and informal . The formal tables are the ones we are familiar with and often encounter in user manuals . Tables that have proper titles and column headings belong to this type. Information in these type of tables can stand on its own. These tables are usually placed closer to the text. I feel the common look-up-a-value table is a an example of a formal table. Informal or in-line text tables do not have columns or titles. They are part of the text and are self-explanatory. For me, they look a bit odd in documents. Decision tables allow the user to take a decision and distance tables show data or values related to categories. Structure of a Table A table is identified by a brief and a desc...

In discussions, I hear the words "user stories" and 'use cases" used interchangeably. This wikipedia link details what exactly a user story is. Wiki explains User Case .

Geoff Hart rips apart the myths in technial writing. Great post.

Technical writers all over the world are debating on how new approaches and processes can dramatically improve the quality of the documentation produced. A few suggest that Usability testing, even with limited resources, can add value to the documentation you produce. Other suggest moving documentation to the Web 2.0 model for ease of use and adopting agile documentation. There are people who cite Google's example of comic documentation when they released their new browser, the Chrome. Daniel Brolund suggests User Guide driven documentation where a snippet of the user guide describing a new feature is prepared. This is an interesting idea in that the techncial writers get a chance to become involved in the documentation process at the initial stages of software development itself. Click here to read Daniel's post.

Google while unleashing its new browser Chrome, has created another great stuff. It's a comic book about the browse. Check it out at http://blogoscoped.com/google-chrome/2

While reading an STC newsletter, I found that folks at Oracle use a tool called Qarbon ViewletBuilder. This was a piece of news for me. After a bit of browsing, I found that the tool can be used to create online presentations, demos, and e-learning modules. Callouts, notes, and audio content can also be added to online presentations created with this tool. My favourite tech blog Labnol (http://labnol.blogspot.com/2005/06/qarbon-viewletbuilder-imagine-power-of.html) says that technical writers untrained in Macromedia Flash authoring environment will find this tool very easy to create Flash presentations. With the ViewletBuilder, all you have to do is to simply move the cursor over the screen captured. The Flash tutorials or simulations created with this tool can be easily previewed. The tool enables your presentations and demos to reach a wider audience than before. ViewletBuilder works only with Windows and Linux.

The noun diagram is also a transitive verb. Check Merriam Webster .

"a substantial number got into the field without having a clear picture about the job they were supposed to do," said a survery conducted several years back. I liked this particular observation because nothing much has changed for the better. Most of the product-based Indian companies do not have a proper technical documentation team. They are also unaware of the importance of technical documentation in marketing their products. Companies do not have guidelines or styles developed to suit their needs. In the absence of credible data on how many Indian technical writers are writing technical documents from scratch and by testing software, it cannot be said that technical writing has arrived in India. Except for a few private training institutes, who make money in the name of training wannabe technical writers, techncial writing is not yet a lucrative profession in India. When compared to the youngsters joining the media, the standard of English demonstrated by young technical...