The Art of Technical Writing 2.0

Two posts in one day is a first for me. At least on this blog

Was reading this post on the Men With Pens blog and it made me think. Do read that, it is a nice post.

For the past few days I have been observing the variety of styles in which emails are written. Here are a few:

Subject = Email

This is not bad at all but one must append “<eom>” at the end of the message. It’s not a good idea to put a link in the subject though, for the simple reason it may not be clickable in some Emailing services.

No Salutation

I actually like the absence of salutation. though it could come of as rude. I might not do it unto others but don’t mind it done to me. For office communication ‘Dear XYZ’ is out, one must just reserve it for their dear ones. A ‘Hi’ or ‘Hello’ is what I use usually, but I will gladly do away with it, if we all do. It isn’t reeally required. Don’t you think so?

Endgame

This is treacherous and it looks really silly, when person has signed name and has a signature below with the name again. And a good way to sign off is, ‘Best’, ‘Regards’, ‘Thanks’ (but there should not be more than one thanks in one email. Again we can do without it. But this a personal touch, and sometimes in a dry email, this is all there is.

Body

I came across this site suggested in one of the comments on men with pens blog - five.sentenc.es - and I like the idea of keeping the email size, 2-5 sentences. Though don’t make the sentences long and winding like a bad school boy. Once in a while when you have more to tell it can’t be avoided.

Multicolored In-line Comments

Have you come across such mails? They are the most fun. And are close to being an online catfight. It’s best avoided as it shows aggression. It can be met with only two reactions, the calm will laugh at you and the angry will write back with equal fervor (much to the amusement of the calm, who could be the third person on mail). If you have to answer things, I would suggest make bullets and keep the message in the thread.

Gmail Threads

Gmail is worth being purely for this feature.  It can be used as a social messenger (alongwith the Reply All capability). Though this is not recommended in official correspondence, only amongst friends who have loads of time.

Reply All

This is scary. I am never sure when to reply and when to reply all. Sometimes it’s not a difficult decision, when pure information is being distributed. But when you are distributing what you “think”, be sure you are not offending anyone.

And finally, don’t use these tips for love emailing. Remember your target audience here too.

Am a couple of days late on blogging about this - House passes bill requiring plain language in federal documents.

I love plain language. I am a writer first and then a technical writer. And I still love reading Wodehouse. Have attempted reading Joyce. Love what Ghalib does to Urdu. And occasionally, mischieviously indulge in writing cryptic prose or poetry with words obviously borrowed from Wordweb and forgotten as soon as they are used.

And, I think keeping it simple, stupid! (KISS) Is far more difficult.

But the act will make life simple for my fellowfolks in US. I wonder if we can get such a law to be passed in India. Whenever I read official papers, my mind feels like it is in a virtual giant wheel. A few years back, I needed to make a lease agreement. I downloaded one from the net, after reading it, I almost decided to not give my house out on lease. Then courageously, I took up the challenge and rewrote the entire document in simple English. My mom scared me by saying, they may not accept it. Thankfully no one noticed that they could understand what was written.

Here’s a little bit about Plain language and here’s the Plain Language Act.

Ok, now all of you say - Hail Plain Language - this is a much better dictator.

(This post is for my friends who have not yet discovered the goodness of RSS feeds.)

Firstly what is a feed?

One eats food at regular/irregular intervals. Let’s say that every time you eat, it constitutes a feed. Similarly many sites publish content at different intervals. And every time fresh content is available, it means there is something new available to consume, hence feed.

How it works?

In most news sites and blogs, content is arranged in a particular manner. A blog post can have the following different parts - title, date, blog post text. Usually when content is arranged in such a manner it is “feed friendly” and it is easy for RSS softwares to read them and display them in different feed readers.

How can it be useful?

You love to read a variety of blogs and news sites but it may not be easy to remember and follow them all. Bookmarking is an option but it does not inform you of updates. So if a site has an RSS feed, you can subscribe to it and get the content delivered to your feed reader, which is similar to your email inbox.

How do I know if a site has an RSS feed?

Usually all sites that have a feed associated with it are designated with the RSS icon. Latest web browsers also indicate if the web page has an RSS Feed. In Mozilla Firefox it appears in the area where the URL appears. In case of Internet Explorer 7.0 it usually appears in the toolbar area.

The RSS feed icon looks like this -

How do I subscribe to an RSS feed?

This can also be done in multiple ways. One way is give your RSS feed reading software the URL of the site and let it find a feed that you can subscribe to.

Or

You can click the RSS Feed icon on the web page. Clicking this icon, usually displays the RSS feed. (This is a stripped down version of the site.) For example compare these two pages -

NY Times Home page: http://www.nytimes.com/

NY Times RSS Feed: http://graphics8.nytimes.com/services/xml/rss/nyt/HomePage.xml

You can add the blog/webpage  URL in your Feed reading software, and the software will subscribe to the feed.

Where do I find a good feed reader?

I use the Google Reader, if you have a Google account, you can start using it here - http://www.google.com/reader/

There are many such online and offline tools. Do a google search and you will find more softwares.

More Questions?

If you have more questions, add them as comments and I will try to answer them.

Theory: A technical writer gives good directions.

Why?

A good technical writer needs a few skills to do the job well and while some of this can be something that one can be born with, one can also have developed it over the years. The skills I am talking about are described below.

Assimilation - The power to understand things quickly. To give good directions, one needs to know their way around. For being good at giving directions in particular, having a good visual memory helps. Making a mental note of things and putting it on a map in your head and marking it with specific landmarks is quite a droolable quality.

Good grasping power helps to understand what you are going to talk about. While this skill is not a rarity, it definitely is either inherent within a person or a person has to consciously develop it. It need not come with a particular type of education.

Simplification - There could be ten ways of reaching point B from point A. But the best way will be different for different people. As the crow flies, he might have a totally different take on the best route. ‘Simplification’ here would mean, avoid the short cuts if they are too confusing and state landmarks that are visible to the eye. Your aim is to get the person to the destination quickly and without him/her losing the way.

One can develop this skill, solving math problems in school. If one gets a hang of simplifying math problems, the skill can be applied almost anywhere else. And definitely in providing good directions or in technical writing.

Translation - ‘Translation’ here would mean actually telling what one assimilates and simplifies. This is not an easy task. One needs to be able to speak the language of the person who is receiving the directions. A good communicator will make the language appear as small a barrier as possible.

One could have grasped these skills while learning languages at school. A good hand at grammar would definitely be invaluable.

A good question to ask —

So if you meet a technical writer and want to hire him/her, ask for directions to a local book store and tell the writer that you don’t speak his/her language. A good tech writer should overcome the challenge.

Religious texts are based on the cultures of the times they were written in. They are user manuals in a way but the style used in them is very different from any user manual of today. In fact it is closer to poetry, where at times there could be multiple meanings that could be derived from them. A user manual is definitely unacceptable if it has more than one meaning.

It would be interesting to know, if it’s the language evolution that has made these texts seem abstract or were they meant to be written in a manner, which would be acceptable over many years. After all poetry does have a longer life than a technical manual. I would be analyzing a few religious texts on this blog in the future using the tag Religion & Technical Writing.

First a promise I need to make to myself -

“I shall write here more often, God-willing.

Little blogs, mo-blogs, one-line posts, twitters or jaikus, call them what you want, but the world seems to have taken a liking towards this brand new way of saying thoughts into condensed sentences. The words here do not flow into streets that follow like a tedious argument of insidious intent (that’s an Eliot line). It’s short and it’s sweet (at least in thought).

Webaroo (that’s where I work), has started a similar service. Though the service is currently available only for the Indian market, it still has a better way to reach its users. There is no sign-up required either to create a group or to read the content. SMS GupShup is what it is called and the blogs are called groups. The term blogs is still not as widely known or accepted in India.

I have been on SMS GupShup with my CityHaikus group. And its good to see that I have 52 subscribers, much more than the number who read this blog. Just shows that people love to consume in small packets. The service definitely has a future. It just needs to be built well and with a lot of thought.

Here’s a widget that contains some of my posts on the CityHaikus SMS GupShup group as well as some of the groups that I love and follow.

The widget is created by thakkar, some really hard and cool work. Its cool, but too much branding on it

When I was a dud, which is not very long back (I probably still am), I created a flickr account. Excited by the promise that it is a great way to store, search, and share photos. It is, but did you know that it only allows you to store 200 photos with a free account?

When I crossed that limit, I decided to explore flickr.

Here’s where I heard the word ‘Tags‘ (in the web 2.0 sense) for the first time. Tags are words (or phrases) to identify a photo (in flickr’s case). A photo should usually have multiple tags. It is also necessary to tag photos appropriately as flickr let’s you search photos by tags. The concept is simple (and brilliant) but I took some time to grasp it due the inertia of ignorance.

One of my first tag searches on flickr was for frogs (I love the creature), and I was amazed by the number of beautiful photos I saw. I spent an hour seeing frog photos.

Go ahead see some beautiful photos of your favorite things. You can try searching for your name and see if you get any photos.

There’s more to flickr than just tagging. I hope to continue in another post.

Here’s a design style guide that says things simply and beautifully.

It also pushes the argument that Web 2.0 is not merely a concept anymore, it has taken concrete shape and we are in the midst of a movement. The great thing about this movement is that it has a class of its own. When this movement comes to a pass the remains will be worth dedicating a museum too - like say the Louvre.
I have a feeling that I will be referring to this guide very often in the coming few days.

“Simplicity, according to me too will form one of the most necessary features of Web 2.0.”

In the next post we will explore how we can apply it to writing style.

Web 2.0 is the age of information.

Our ancestors lived in an age when the only way to access knowledge was through books. Between the time when my grandfather gifted me my first encyclopedia to today where I actually have edited a few entries on Wikipedia, man has traveled a long way.

The age of Web 1.0 was a phase when Internet was accessed by the elite and the erudite. The new version of the Web has made memory redundant. All you need to know is your email password and you are fine.

Today I was talking to one of my friends and she told me that a mutual friend of ours recently celebrated her birthday. I said that I must wish her belated happy birthday. She said that I was shameless.

I said that we Web 2.0 people are quite shameless.

Here’s the Wikipedia page on technical writing.

To exemplify what it is, it says: “A simple everyday example of technical writing is a recipe for baking a cake.”

One of my favorite ways to test potential technical writers is to ask them to write - ‘How to make a sandwich’. Apart from a 100 different recipes, you may find a good technical writer.