Common errors in technical writing

Today I attended a session of the Mumbai chapter of the Society for Technical Communication . The first session was by Gurudutt Kamath, who is probably the most well-known figure in the tech writing community in India. My interest in attending the session arose cause someone I know was also speaking there, and also because a lot of the work that we do involves a significant amount of technical writing. So while, we may not be professional technical writers, consulting does require us to have excellent written communication skills.

Guru (as he is popularly known) was speaking on common errors in technical writing. I think many of these errors occur in daily business communication as well. He made it a pretty interactive session, so the other tech writers also piped in with the errors they have seen occur most often. Here's the list we came up with:

1. Not identifying the purpose of the document. Each document should have a set of objectives and a context in which it is being developed. Is it a user manual, or a marketing collateral, or something else. This leads us to:
2. Not identifying the right target audience. If you don't know whom you're writing for, you're quite likely to miss the mark in terms of getting your point across. You could come across writing increasingly dumbed-down documents, or your writing could be so filled with jargon that it would be impossible for the average reader to understand. Having identified the target audience, you need to be sure that the next error is taken care of:
3. Not getting the right sample audience to review your document. The right reviewers can make a huge difference in the final quality of your writing. I have often had non-technical editors review some pretty technical articles, and miss out on stuff that a more technical reviewer would easily have helped improve upon. Some of the better journals have a peer review system, so you ensure that a wider sample audience reviews your writing. A lot of the times, we end up submitting stuff without review - which is almost sacrilege!
4. Inconsistency. Whether it's your formatting styles or your use of numbering systems, or your choice of words (British English or American English or apna Indian English), you have to be consistent. This also applies to:
5. Not selecting the right examples. Guru gave the example of an article, which was about choosing relevant examples, and was woven around Amercian baseball. Now the author might have written the original article for an American audience, but by the time it got syndicated, it was published in other regions, where most of the baseball metaphors fell completely flat.
6. Common grammar and spelling mistakes. "It's" vs. "Its". Not pressing the F7 key. Enough said!
7. Wrong references. In larger documents, references to sections or figures within the document can go wrong when the document changes. For a book, that I was recently co-authoring, I had to keep changing the references to snapshots and figures as I kept inserting more, requiring me to renumber the earlier ones, as well as change references to them. Apparently, the right way to do it is to add a reference field, and point it to the location within the Word document, so that when the referenced section changes, the reference changes with it.
8. Cookie cutter nightmares. Ok, so we've all done this. Opened up a previous proposal or report, and simply pressed File Save As, and the old client name pops up in the most embarrassing places. We once failed to get a customer reference, because during the closing meeting they brought up the point that they had been put off because an old client name had cropped up in one of the documents we had submitted in the project. Based on the inputs from the other participants in the session, this happens to the best of them.
9. Use of cliched graphics. Using the MS supplied clip art in Powerpoint presentations, not getting the graphics done professionally, and using irrelevant graphics. Of course, Powerpoint gaffes are a whole thesis subject by themselves.
10. Punctuations errors. I am most guilty of these, especially with mis-placed commas. Just don't seem to get them in the right places! Other errors include inconsistent quotation marks, misplaces colons and semi-colons, the use of ;&amp instead of 'and', etc.

Guru recommended "The Elements of Style" as a good first book to get your technical writing in good shape. Others also recommended the "Microsoft Manual of Style" and the "Chicago Manual of Style". Guru also has a whole series of articles on common errors on this website.

Changing chartered accountants

I keep harping to everyone about getting a good CA when you start your business. Looks like I should have been taking my own advice.

When we started out, the first CA we got was someone who came in through family contacts. He had been doing the income tax returns for some family members, and we thought it's a good idea to give my company work to him as well. When we were running a small operation, and ledger entries were a dozen a month, it was all good. But as we started to grow, this person proved unequal to the task. Minor hassles such as taking all our files and papers over to his office suddenly became major hurdles in getting the work done. What used to be one box file, was now a dozen and then some.

We started to look around for another CA, and just when we found one, we were told that we needed a no-objection certificate from the first guy in order to start dealing with the new one! Sheesh! Now this was a really delicate matter. Not only was the first chap doing my accounts, but he was also doing those of many more family members now. This meant he was privy to a lot of accounting information.

Anyways, the break came recently and in a very unexpected manner. We moved a couple of family member accounts away from him, since he lives at one end of town, and we at the other. That was an excellent reason to tell him that the entire process of dealing with someone who rarely visits us at home or office was proving to be too cumbersome. The next day he called us to say that he was upset at this decision, and had therefore decided not to do the rest of our accounts either. Of course, this decision comes at a very precise moment - 31st October is the last date to file our company income tax returns.

Thankfully, we have a good accountant working for us. Recently when doing the returns for my father, his insight into some of the laws related to stock investments resulted in a significant tax savings. This was something the CA should have been doing! Again the fees of a CA or the salary to an accountant is usually well worth it in terms of the savings they bring in and the accounting discipline that helps keep a better handle on one's cash flow.

The same situation occured with the Company Secretary. After promising to bring our documents up to date (we had been very lax on this front), and even taking half his fees in advance, he never showed up again. This is the same guy who had done our initial registration. Finally, we got a new CS to work for us, and filed in all our returns with the Registrar of Companies, and ended up paying a lot of back arrears and penalties as well. Yikes!

HP's boardroom scandal - update

I had posted earlier about the HP scandal that forced its chairperson Patricia Dunn and Chief Ethics Officer Kevin Hunsaker to resign. In the post I mentioned that it would have been best if HP had made a clean breast of the entire issue at the first instance, and not waited until things got muckier.

The latest news is that the California Attorney General has indeed filed criminal charges against Dunn, Hunsaker and the others. The most interesting note is the use of computer forensics to unearth much of the evidence in this case. Although, one accused is reported to have destroyed his hard drive with a hammer - pretty effective I must say. I'll go out on a lark here and predict that the new HP CEO, Mark Hurd might have to end up resigning too, because its quite likely he knew pretty much enough about the whole "pretexting" investigation to make the call that they were indeed crossing the line.

CNet News has a comprehensive coverage of the entire story, which promises to reveal a lot more about what went on behind the scenes at one of America's largest corporations.

Another related item on corporate ethics is Steve Jobs' apology to shareholders where certain stock option grants were pre-dated so that they were shown as being given on an earlier date when the share price was lower, thus bringing immediate benefits to those who received them.

The simplest SEO formula - it still works!

Whenever I speak with any budding entrepreneur, I cannot help but stress the importance of search engine optimization. Over half our business comes through enquiries generated through our website. In fact, in the first four years we never had a dedicated sales/marketing team, and still managed to earn 6-figure revenues through consulting.

About a year ago, we shifted our domain from a .co.in to a .com. And also changed our branding to reflect our global aspirations. As a result, all the SEO that we had done on our original domain came to naught. Our Google page ranks for the new website were less than 3 on most pages, and our website was simply not turning up in search engine results. So obviously, business enquiries almost suddenly dropped. We took it up on priority to boost our page ranks and get back to the levels we were on with the previous domain. And from that emerged vindication that our SEO formula still works, and is as simple as this:

• Build a nicely designed website - everything is logically structured and your services, products and company profile are well presented
• Add good content to the website. Ours carries a lot of articles that our team writes, and a couple of blogs
• Identify the keywords that you think potential customers would search for
• Add these into your title and meta tags
• And the key to it all - have other high-ranking websites link back to you. This is main challenge, and you got to put up great content, which people will read because it's interesting, not because you're trying to sell it to them directly.
  

A couple of days ago, the latest Google crawls had just finished - our page ranks were 5 or 6 on all the pages, and we were figuring in the top 5 results for most of our identified key words and phrases. And the most significant proof - business enquiries through our website have gotten back to their previous levels! So if you're getting into business - any kind of business - pay attention to SEO, and you'll go a long way in aiding your sales and marketing efforts.