Posts

Showing posts with the label technical writing

Using Wordpad to assess writing skills of a technical writer candidate

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...

The Lift

There were two lifts in that building. In front of one of the lifts, there was a blue chair, that cheap plastic variety I would have bought if I were a slum dog. The chair was facing the lift as if they were engaged in an infinite conversation. The other lift seemed to be working and a yellow flash of light showed that it was coming down. The lift opened, I said second floor to the lift operator, went to where I wanted to go, and climbed the stairs down as the lift had no buttons. The only sure destinations were the top floor and the ground floor. As I made my exit, I saw a man lying on a tree branch. The tree did not have much leaves and the trunk was dark. I thought of cutting one of the branches, or simply pushing the man down. Then I decided to walk towards the left from where a strong smell of fried fish was wafting in.

The worst crime by an editor or reviewer

Have you ever wondered what constitutes a crime committed by an editor or a reviewer? In the days of proofreading, there were standard symbols associated with the changes to be made in a copy or manuscript. When it came to desktop publishing, the editor or reviewer used to turn the Track Changes feature in a word processing software like Microsoft Word on. Technical writing tools such as Adobe FrameMaker and Madcap Flare enable commenting on a document. Adobe Acrobat allows comments in PDF docs. So, despite all these modern facilities, what if someone goes to the extent of editing text on the sly in a document? Edits that the poor writer discovers later and finds them damn wrong. One reason may be overconfidence. The reviewer would have been so overconfident and would have never imagined that the edits would be wrong. The reviewer must not be knowing that industry practice provides the benefit of doubt to the writer. The mantra, "When in doubt, check it out." applies to...

Google Analytics and Flare HTML 5.0 projects

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.

Word 2007 error - This file is read-only

Image
Consider that you are working on a very important document and your manager wants it immediately. After a few minutes, you click Save . And to your surprise, the Word 2007 document says that "This file is "read-only". Shocked and no time to do a Google search? The solution to this annoying pop-up screen is very simple. Do the following steps to avert this problem: 1. From within the Office 2007 document, click the Office button or Ribbon. 2. Click the Word Options button. 3. Click Advanced in the Word Options screen that appears. 4. Scroll down to the Save section. 5. If the Allow background saves box is selected, click once to clear it. 6. Click the OK button, and reopen the document. Note : Repeat these steps if you get the same error again.

An Act for Plain Writing

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!

Walk in, Walk In, or walk-in?

Is it Walk in, Walk In, or walk-in? The word, walk-in , appears as a noun and an adjective in Merriam Webster online .  I could not find the word without the hyphen. The Oxford Advanced Learners Dictionary website showed the hyphenated word only. As you know, the word means someone who walks in to a place without an appointment. Typical examples are walk-in customers for a bank, walk-in interviews for fresh graduates, and walk-in patients in a hospital.

Editing Technical and User Documentation

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...

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....

New Screen Capture Tool

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

The Thing Called Relational Database

I have attended meetings that often discussed and questioned how the product I document on access or query the database at the implementation level. While a few of these 'technical' discussions do not make much sense, it usullay creates a sense of curiosity to know a little more on the topic. It was with much interest that I read, Is the Relational Database Doomed? , an excellent piece on relational databases and alternatives. I cannot help myself from telling that this is a great piece of 'technical writing. Great post!

Social media and technical writers

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...

Jyoti Sanyal's Book and Technical Writers

Jyoti Sanyal was a former assistant editor and columnist for The Statesman. His book, Indlish, is an excellent guide to how Indians should use contemporary English. The book is an essential read for those in a writing career, including technical writers and journalists. The author identifies the four "grey" areas Indians fail to rectify in their writing. He also provides examples and tips on how these gaps can be plugged. The following grey areas pinpointed by Sanyal in his book applies to technical writing as well: Syntax : A primary reason why overseas clients dub Indian technical writing as bad is the writer's abject failure to understand the English syntax. Very few has a good understanding of the sentence structure and rules that govern sentence structure. Very few spend time to learn how English is used all over the world. Most of them consider writing long sentences as equivalent to their mastery over English. Technical writers argue with editors saying that a ...

Let the classics remain as classics

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 ...

When everything is vague

"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 does a writer die?

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...

The problem of using 'You"

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...

Reading blogs

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.

Parts of a table

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...

Words that drive me mad

I feel like thrashing my desktop or banging my head against the wall on seeing the following words in user documents and emails: On approval or once approved Bolded Revert back Impacted The problem with the first word is if the user has to do an action after a particular step or authorisation, I can write, "After xyz task, ...". Why should the word "once" be used? In the printing industry, the word "bold" stands for "boldface". It is a character or type set in boldface. According to a printing glossary , "Bold is a type that appears darker than the next type of the same typeface." The adjectives are bolder and boldest, and not bolded . Technical writers can use make bold or set to bold instead of bolded that gives a puking sensation . The same applies to impacted . Even though, this is a popular , I will substitute it with another word or rewrite the sentence. I do not know who discovered the expression "revert back" as...