N8UAHEDHN3C5

Ingredients of Good Documentation:#1

Simple language

A technical writer colleague of mine once wrote the following in tutorial meant to explain business rules:

• YoungRule – Rule to be applied if the applicant is less than 25 years old
• MiddleAgedRule – Rule to be applied if the applicant is between 26 and 50 years old
• Codger – Rule to be applied if the applicant is more than 51 years old

A few weeks later one of our customers wrote a support mail pointing out that there was a mistake in our tutorial. The rule called “Codger” should perhaps read as “OldRule”.

He was right; but my colleague was not wrong either. A quick look at the dictionary will tell you that the word codger means old man.

But that’s the point – do you really want your reader to make a dash for the dictionary while reading your user guide?

Managing Career and Expectations

Here’s an excerpt from a speech given by Mr. R. Gopalakrishnan, Executive Director, Tata Sons, at IIM Ahmedabad. Things that nobody will teach you at your B-school:

There is a Thai saying that experience is a comb which Nature gives to man after he is bald. As I grow bald, I would like to share my comb with your people, about their career ahead.

1. Seek out grassroots level experience
I studied Physics and Engineering at University. A few months before graduation, I appeared for an HLL interview for Computer Traineeship. When asked whether I would consider Marketing instead of Computers, I responded negatively : an engineer to visit grocery shops to sell Dalda or Lifebuoy? Gosh, no way. After I joined the Company and a couple of comfortable weeks in the swanky Head Office, I was given a train ticket to go to Nasik. Would I please meet Mr. Kelkar to whom I would be attached for the next two months? He would teach me to work as a salesman in his territory, which included staying in Kopargaon and Pimpalgaon among other small towns. I was most upset. In a town called Ozhar, I was moving around from shop to shop with a bullock cart full of products and a salesman’s folder in my hand. Imagine my embarrassment when an IIT friend appeared in front of me in Ozhar, believe it or not! And exclaimed, “Gopal, I thought you joined as a Management Trainee in Computers”. I could have died a thousand deaths. After this leveling experience, I was less embarrassed to work as a Dispatch Clerk in the Company Depot and an Invoice Clerk in the Accounts Department. Several years later, I realised the value of such grassroots level experience. It is fantastic. I would advise young people to seek out nail-dirtying, collar-soiling, shoe-wearing tasks. That is how you learn about organizations, about the true nature of work, and the dignity of the many, many tasks that go into building great enterprises.

2. Deserve before you desire
At one stage, I was appointed as the Brand Manager for Lifebuoy and Pears soap, the company’s most popular-priced and most premium soaps. And what was a Brand Manager? “A mini-businessman, responsible for the production, sales and profits of the brand, accountable for its long-term growth, etc., etc. I had read those statements, I believed them and here I was, at 27,”in charge of everything”. But very soon, I found I could not move a pin without checking with my seniors. One evening, after turning the Facit machine handle through various calculations, I sat in front of the Marketing Director. I expressed my frustration and gently asked whether I could not be given total charge. He smiled benignly and said, “The perception and reality are both right. You will get total charge when you know more about the brand than anyone else in this company about its formulation, the raw materials, the production costs, the consumer’s perception, the distribution and so on. How long do you think that it will take?” “Maybe, ten years”, I replied, “and I don’t expect to be the Lifebuoy and Pears Brand Manager for so long”! And then suddenly, the lesson was clear. I was desiring total control, long before I deserved it. This happens to us all the time – in terms of responsibilities, in terms of postings and promotions, it happens all the time that there is a gap between our perception of what we deserve and the reality of what we get. It helps to deserve before we desire.

3. Play to win but win with fairness
Life is competitive and of course, you play to win. But think about the balance. Will you do anything, to win? Perhaps not. Think deeply about how and where you draw the line. Each person draws it differently, and in doing so, it helps to think about values. Winning without values provides dubious fulfillment. The leaders who have contributed the most are the ones with a set of universal values! V Mahatma Gandhi and Martin Luther King for example. Napoleon inspired a ragged, mutinous and half-starved army to fight and seize power. This brought him name and fame for twenty years. But all the while, he was driven forward by a selfish and evil ambition, and not in pursuit of a great ideal. He finally fell because of his selfish ambition. I am fond of referring to the Pierre de Coubertin Fair Play Trophy. It was instituted in 1964 by the founder of the modern Olympic Games and here are two examples of winners. A Hungarian tennis player who pleaded with the umpire to give his opponent some more time to recover from a cramp. A British kayak team who were trailing the Danish kayak team. They then stopped to help the Danish team whose boat was stuck.The Danes went on to beat the British by one second in a three hour event! What wonderful examples of sportsmanship! Play to Win, but with Fairness.

4. Enjoy whatever you do
Sir Thomas Lipton is credited with the statement, “There is no greater fun than hard work”. You usually excel in fields, which you truly enjoy. Ask any person what it is that interferes with his enjoyment of existence. He will say, “The struggle for life”. What he probably means is the struggle for success. Unless a person has learnt what to do with success after getting it, the very achievement of it must lead him to unhappiness. Aristotle wrote, “Humans seek happiness as an end in itself, not as a means to something else”. But if you think about it, we should not work for happiness. We should work as happy people. In organizational life, people get busy doing something to be happy. The more you try to be happy, the more unhappy you can get. Your work and career is all about you’re reaching your full potential. Working at one’s full potential, whether it is the office boy or the Chairman, leads to enjoyment and fulfillment. A last point about enjoyment. Keep a sense of humor about yourself. Too many people are in danger of taking themselves far too seriously. As General Joe Stilwell is reported to have said, “Keep smiling. The higher the monkey climbs, the more you can see of his backside”.

5. Be Passionate about your health
Of course, as you get older, you would have a slight paunch, graying of hair or loss of it and so on. But it is in the first 5 – 7 years after the working career begins that the greatest neglect of youthful health occurs. Sportsmen stop playing sports, non drinkers drink alcohol, light smokers smoke more, active people sit on chairs, and starving inmates of hostels eat rich food in good hotels and so on. These are the years to watch. Do not, I repeat do not, convince yourself that you are too busy, or that you do not have access to facilities, or worst of all, that you do this to relieve the stresses of a professional career. A professional career is indeed very stressful. There is only one person who can help you to cope with the tension, avoid the doctor’s scalpel, and to feel good each morning – and that is yourself. God has given us as good a health as He has, a bit like a credit balance in the bank. Grow it, maintain it, but do not allow its value destruction. The penalty is very high in later years.

6. Direction is more important than distance
Every golfer tries to drive the ball to a very long distance. In the process, all sorts of mistakes occur because the game involves the masterly co-ordination of several movements simultaneously. The golf coach always advises that direction is more important than distance. So it is with life. Despite one’s best attempts, there will be ups and downs. It is relationships and friendships that enable a person to navigate the choppy waters that the ship of life will encounter. When I was young, there was a memorable film by Frank Capra, starring James Stewart and Dona Reed, and named IT’S A WONDERFUL LIFE. It is about a man who is about to commit suicide because he thinks he is a failure. An angel is sent to rescue him. The bottom line of the film is that “No Man is a Failure Who Has Friends”.

Conclusion
My generation will never be twenty again, but when you are older, you can and should be different from my generation. Ours is a great and wonderful country, and realising her true potential in the global arena depends ever so much on the quality and persistence of our young people. Good luck in your journey, my young friends, and God be with you.

Making Money Online

Everybody on the internet seems to be talking about making money online, using viral marketing strategies to make a quick buck, or becoming a millionaire by setting up online businesses.

Also, its not just about becoming millionaires – most smart people could earn as much given reasonable time and opportunity. Its about making that much of money fast, without sweat, and even when you are sleeping.

Specifically for writers, there are several prescribed “tricks” – offer freelance services on websites like Elance; publish and sell e-books online or even give them away for free; or simply translate books written by other writers into local languages and sell them online as an authorized reseller.

Of course, this millionaire frenzy hasn’t yet taken India by a storm. But I wonder what we Indians think about this phenomenon.

Do you think it is possible to become millionaires overnight? Or are we missing something here?

Send in your comments.

7 Must: Starting Your Business

Planning to start your own business? Decided to be your own boss, lay your own rules, and follow your passion? Here are some tips that helped me immensely when I decided to take the plunge:

1. Answer the obvious question first

• What do you want to do? Why?
• What are your differentiators? 
• Do your customers want it?

The last question is probably the most important and yet the most difficult to answer. Your customers are not going to spend money on what you are offering unless you give them what they are looking for. They need to see value in your product / service.

While at this, make sure to write down these answers rather than just visualizing them in your mind. Put them down on paper, and you’ll find yourself thinking with a lot more clarity.

2. Write a business plan

Once you have put down your business idea in words, start building on it to create a formal business plan – the more detailed, the better. Here are some important questions that you will be forced to answer in your business plan: 

• How much do you need to invest? Where will the money come from?
  In an ideal scenario, your investment must come from your savings. It’s really not such a great idea to borrow from family and friends unless they have a stake in your company. Remember to budget upfront for purchasing legal software and obtaining requisite government sanctions. 
• How will your product / service be priced?
  Pricing can be a very tricky topic. But as a domain expert, you’re probably best equipped to handle it. Beware of undercharging or over estimating your worth. Also, pricing is a dynamic parameter. So it might be worth creating different versions of your business plan based on different levels of pricing.

3. Is your family ready to take the plunge?

Your business is your baby. It is bound to change your family dynamics. Ensure that your family members know what to expect. Of course, they’ll support you.

4. Consider bringing in a partner.

Two is always better than one. Find someone who shares your passion and is as good or even better than you in your chosen domain. It would be best if your partner brings in skill sets that compliment yours. So if you are great at technology, you could choose a partner who is great at sales and marketing.

5. Make sure to comply with all statutory and legal requirements

You don’t have to become a legal expert to start your company – you just to need hire the experts. Consider hiring a competent chartered accountant to help you manage statutory requirements such as company registration, service tax registration, etc. Let a seasoned lawyer help you write out contracts, copyrights, and NDAs instead of trying your hands at it yourself.

6. Get more organized than ever before

Keep professional and personal expenses separate right from the start. Keep record of everything you do and every penny you spend. Put a simple yet scalable filing system in place for all papers relating to your business.

7. Draw out a detailed operational plan

Here again, the longer you spend planning, the easier it will be to implement.

• Private Limited Company or partnership?
• Work from a home office or hire office space?
• Employ people? If so how many and with what skillsets?
• Outsource work or work with consultants?

These poitners are far from exhaustive; but they are a good way to get started…

The Dark Side of Technical Writing

This is a must read for all aspiring technical writers. You’ll probably find a lot of information about technical writing being a great career to pursue. Here’s another viewpoint published by Keith Hood. Never hurts to see both sides of the coin and take an informed decision:

” If you’re thinking in career terms, the problem is never getting the same type of job. Employers always hire because of your last two or three jobs. The problem is if you decide you’ve had enough of tech writing and want to try something else. People don’t look at your resume and wonder if your 8 years of experience as a tech writer would make you a good production manager. If you do think about doing something other than technical writing, you have to make the change early enough that you don’t become over specialized.

Everything I write from here down applies to some extent to every high-tech industry. A little less in companies that actually manufacture things, but very much so in software companies.

Here is the raw, unvarnished truth: If you want to make a life as a technical writer, you must sustain yourself by your enjoyment of writing, because you cannot get any satisfaction from your work any other way. For you there will not be the kinds of rewards that others can expect. Raises, promotions, company perks of some kind – forget them. You won’t see them. Technical writing will always pay significantly less than engineering or a type of work that is more central to the company’s business.

Technical writing is no longer considered a skilled IT field. It was, up until the tech stock crash of 2001. Now, technical writing has been commoditized. Since the tech bubble burst, companies have been doing everything they can to get leaner but still shovel out as much or even more product. The single largest expense (at least for software firms) is payroll. Payroll expenses are very much a function of time needed for product development. So, companies have been dedicatedly finding the absolute minimum number of people they can keep on hand and still be able to function. Cutting personnel costs has become one of the top 5 maxims in high-tech companies. This is why “outsourcing” and “offshoring” became industry standards.

Nowadays, tech writers are a dime a dozen. Companies hire them as needed and discard them when the immediate need is past. Companies will hire programmers and DBAs and QA personnel as regular employees because they have a direct effect on the process of turning out marketable product. But tech writers do not. So when a company reaches a point where it needs to field a help system or some other kind of documentation for customer use, they’ll hire a TW on a 6-month contract and when it’s over, he’s out the door.

In late 1999 my boss, the VP of product development for the company, told me, half-joking, that technical writers were considered a necessary evil in business. He said the job description would not exist at all if it were not for the fact that customers expect documentation. Companies don’t want to have to hire TWs because they are a drain on the company’s resources. They have to be paid, housed, and given equipment and support, but what they turn out does not contribute to the value of the product. And since then, his words have been proven by every other place I’ve worked.

Think about the career progress in tech writing –- there really isn’t any. If you are a programmer or engineer, you could have a career path something like this: Engineer > Team Leader > Project Manager > Product Line Manager > Director > VP of Engineering/Product Development > CEO.

A business type or sales could expect a career path something like this: First job > Lead > Region/Product Manager > VP Sales/Marketing > CFO/CEO.

Another IT type like a DBA could expect something like: DBA > Lead Designer > Network Manager > IT Division Manager > CIO > CEO.

Tech writer? Well, to begin with, today almost all technical writers are hired individually and are individual assets for totally separate departments in the company. And that’s if it’s a fairly large company. A lot of tech writing gets done for fairly small companies where you’re the only tech writer they’ll ever have. If they do ever hire more, it’s because they have projects come up for which they need documents, so they’ll hire someone to support that particular project for however long it lasts, and then that writer is out the door.

To have a chance of advancement in tech writing as a TW, you must work in a company which is large enough, and old-fashioned enough, that it has a hierarchical structure related to document production. Such companies are scarce today and getting scarcer. Most such structures for documentation today will be found in government agencies, which opens a whole new can of worms. So if you get hired by a company that has a documentation structure where there is some chance of advancement, how much advancement can you expect? Well, after you’ve worked there several years, you may become a team leader, and run a group of 3 or 4 people. After several more years, you may have a shot at becoming the documentation division manager. And after that, nothing.

There is no path upward from that. Nobody gets promoted into upper management because he’s a good writer. And nobody ever gets promoted because he’s good at managing writers. The upper levels do not consider tech writing important and no matter how good you are at meeting schedules or dealing with problems or fiddling the budget, experience with documents is absolutely meaningless when it comes to deciding who becomes the new VP. What matters is perception of dollar value to the company.

A few years ago, Wired magazine had an article about problems common in database management. It pointed out that one of the worst problems was, there is usually a lack of good documentation. But the same article recommended that the way to handle such problems was during the design phase, and to set up the databases in such a way as to minimize the need for documentation. It basically said that doing a lot of work to ensure good documentation was not cost effective in the long run, because management cares that you give them their data on time, and they don’t care if you do it with or without documentation. The article ended with the oh-so-true observation, “No one ever got promoted for having good documentation.”

One reason most business people care nothing about documentation and what goes into making it is, they think nothing of writing. They are sure it’s easy. They can write — they’ve seen themselves do it. They have no idea just how awful they are as writers, but they think writing is easy so they have no respect for someone who does it for a living.

Also, and more important, tech writing (documentation) is not seen as contributing to the bottom line. There is no way for a writer or a writing department manager to claim that his work made a verifiable difference to the figure at the bottom of the profit/loss statement. And for that reason, anyone connected to documentation will always be considered a necessary burden, at best.

As you go through life you will find upper level management who used to be tech writers themselves. But in every case, you will find they did not go from tech writing to management. They sidestepped. They got out of tech writing and into programming or business analysis, and *then* they started climbing the corporate ladder. The plain fact is, the career advancement ladder for technical writers has maybe one and a half rungs. There is no such thing as a career in technical writing; there is only a succession of jobs, some of which last longer than others. If you want a chance at a true career, which includes the chance to do different things and rise to a better position, either get out of technical writing or don’t enter it in the first place.

Good luck.”

You can read the complete write up here.

What Children Can Teach You About Customers

There nothing more enjoyable than learning from your children. My three-year-old is always teaching me valuable lessons on anger management, time management, and leading a disciplined life in general. I recently realized that observing my child closely can help me learn a lesson or two about my professional customers. Here’s what I found:

You have to give them what THEY want

My child repeated his request for a “blue car” for weeks until I got him one. No, the red and black ones he already had would just not do! One of my customers would not budge until I placed a certain screenshot in a user guide even though it was obviously unnecessary under the given circumstance. See the parallel?

Negotiation is the key

You certainly can’t get anywhere without negotiating with your child – “If you want to paint this picture without messing it up, you have to let me help you”. Well, haven’t we all spent time negotiating with customers who have unreasonable expectations? – “If you want great documentation, you simply have to give me more time.”

Packaging is important

Your child is always attracted towards toys that are nicely wrapped in glittering paper. Same is the case with your customer. Packaging your content is important. You must give due importance to the fonts, colors, background images, and other style elements. Beware of jarring colors and bulky images.

Give them more than they are expecting

Sometimes I give my child a bonus toy for his good behavior. It’s just amazing to see the happiness on his face. It makes my day. With customers too, you can delight them by doing more than what you are expected to do. A delighted customer is an asset for life. They’ll always return to you for their work.

Don’t take them for a ride

If you expect your child to be truthful, you have to lead the way by being a role model. If you lie to your child, he will only follow your example. With customers too, it’s very, very important to be truthful and transparent. If you think you can bill your customer for hours that you have not really spent on their work, you’re asking for trouble. Act respectably and you will get respect and recurring business in return.

7 Must: What a Technical Writer Must Do Apart from Writing

A technical writer’s work is only part writing. To do this part of your job well, there are several other things you must do continuously:

1. Talk to SMEs
   The best source of information about the product you are writing about is subject matter experts (SMEs). Talk to them often using both the formal and informal channels. Sometimes, you’re likely to learn a lot more about the product talking to a developer over coffee than during a closed-door meeting with the entire team. It’s not unusual to find SMEs who are great at their work but don’t fare very well in the communications department. Put such people at ease and don’t intimidate them with your superior communication skills. Try using their local language to make them more comfortable – to your surprise, you’ll find them giving you a lot more information and insight than you could have ever imagined.
2. Keep your ears open 
   Join technical team meetings, status meetings, and even customer demos if possible, and keep your ears open. You will learn a lot about the product’s capabilities, limitations, and customer use cases, which in turn can help you provide richer and more relevant information in your user guides.
3. Become the user – try things out first hand
   Get your hands dirty and do all that you want to tell your customer to do. It may be slightly time consuming, but it will be worth the effort in the long run. Having done it all yourself, you will know exactly what to write about and how to write it best. This approach will also help you sequence flow of information logically.
4. Don’t try too hard to understand everything
   While is good to try your hand at the product yourself, it is a common mistake to try an internalize everything. This is particularly relevant while writing API documentation for example. Remember that you are not the subject matter expert and hence you need not understand everything that’s going on. You need to know “what” happens and in many cases “why it happens”. But you really don’t need to know everything about “how it happens”.
5. Become a proxy quality and testing personnel
   In most organizations, documentation runs in parallel with development. So as you keep writing, make sure to identify and report bugs, inconsistencies, and errors. These things may not be part of your job description; but if you ignore them, your dissatisfied customer will crib them later. Worse, he will hold you responsible for not warning him in advance about them in your documentation.
6. Help identify usability issues
   As one of the first users of the software, you can help catch, if not all, but at least the more obvious usability issues. Many companies now treat their technical writers as part of their extended user experience group. So make sure to contribute your bit to make your product user-friendly. This will indirectly reduce your work load – products that are easy to use need lesser documentation and support.
7. Identify topics with “special needs”
   Make a note of complex topics that users might need additional help with. For example, identify topics that are probably best explained in the form of a video. There are other obvious examples, like ensuring that installation guides are not bundled with the software – users must be able to read it before or while installation. So you can create a special installation guide that is available online.

7 Must: Writing for the Web

1. Define your audience

Anybody from anywhere could stumble upon your writing. But only those who are interested in the subject will go on to read what you’ve got to say. So your audience is not the entire superset of internet browsers, but is, in fact, a very small subset of interested people who are looking for information online. So stick to the subject and don’t try to add unrelated information just to humor random visitors to your webpage.

2. Search Engines also are your audience

Search Engines are your “audience” too. If they don’t find you, your target audience is not likely to find you either. So make sure to play to the gallery by adding relevant tags and titles to your HTML pages and embedding relevant keywords into your content.

3. Say what’s most important first

A typical online reader will quickly scan a webpage to see if it “seems” to have the content she is looking for. If you don’t capture your reader’s attention in the first couple of seconds, you probably will not get a second chance. So make sure to use catchy and, of course, relevant titles and headers to create the right first impression. Say what’s most important first to keep the reader interested in your write up.

4. Create magic with links

On the web, less is more. While readers might be willing to spend hours, even days, reading a book, online readers will not spend even a fraction of that time. You can keep your online articles short and simple and yet pack loads of information into them by using links. Use hyperlinks to break up content into chunks and help your reader systematically navigate through all the information you have to provide.

5. Focus on readability

Reading online is often far more strenuous than reading printed matter. Use fonts and colors that are suited for online reading. Break content into multiple paragraphs to reduce clutter and improve readability.

6. Talk to your reader

Talking to your reader is the best way to get them involved. Use short sentences, simple language, and a conversational tone whenever possible. Your reader would rather look for information elsewhere on the web than make a dash for the dictionary to understand what you’ve written. Use active voice and talk to your readers in first person.

7. Roll out great content without reinventing the wheel

While working on the web, it is always a good strategy to reuse what’s already available out there. You can provide links to related articles so you can stick to saying what you want to say without laying an elaborate foundation for the topic; you can make somebody else’s article the starting point for yours to provide the right context; you could do away with lengthy explanations of certain terminology by simply providing a link to another webpage that does the job in detail. So you don’t have to reinvent the wheel. Do your homework (research) well and work smart.