8

Gone in Sixty Seconds?

Anindita Basu

Sixty seconds is what Nicolas Cage got to steal a car. You get less than 60 seconds to steal the attention of your readers and get them on to your help page. The first 10 words on any page take less than 10 seconds to read and understand, and those words are the ones that tell the readers if that page contains the information they are looking for. This is the reason why opening lines are so important – they are hooks that pull readers on to your help page, especially if the readers are looking at the results of a search and trying to decide whether to click through.

In this article, I list four tips for writing introductory paragraphs. For the first three tips, I give two versions of an example and leave you to decide which is the better version.

Tip 1: Do not repeat the title

Repetition takes up real estate. In a search result, the topics are listed by their titles followed by at least 50 words of the first sentence. The introductory paragraph should state something that is not already evident from the title itself.

Version 1 Version 2
Creating a website

Creating a website – all you need to know. Free guide explains everything step by step. Click here to learn all about creating a website.

Creating a website

Getting a domain name, choosing a hosting service, and writing the web pages are explained in this section.

Tip 2: Do not begin with expletives

Expletives are ‘padding’ that are best avoided when you are trying to fit in the entire crux of a topic into only 50 words. Rephrase the sentence to weed out words such as “This topic contains…”, “There are four different…”, “It is important that…” and get straight to the point. You can elaborate to your heart’s content from the second paragraph onwards, but use the most important words first in the first sentence of the first paragraph.

Version 1 Version 2
Virtualisation

This topic contains information about virtual systems, storage, and networks that can be dynamically allotted for better IT resource utilization.

Virtualisation

Virtualisation improves IT resource utilization through dynamic allocation of systems, storage, and network.

Tip 3: Give a snapshot of what the topic contains

Think about what you are writing. Are you explaining a concept? If yes, define the main point of the concept. Are you describing a procedure? If yes, state why the task should be done — the purpose and the benefit. Are you providing some reference information? If yes, describe what kind of information the topic contains. In other words, make the introduction relevant for the readers — tell them why they should read the topic.

Version 1 Version 2
Installing a Windows Service

Use the installutil.exe script located in the root installation directory to define Windows services for specific functions.

Installing a Windows Service

Automate specific functions to run silently without user inputs by defining Windows services by using the installutil.exe script provided with the installer pack.

Tip 4: Write the introduction after you’ve written the topic

Do begin your writing with an introductory paragraph by all means. But after you’ve written the entire section, go back to the beginning and see if you have captured the essence of what you’ve just written in those first three lines of that topic. This is something that I follow; your mileage may vary.

End Note: If you are writing with DITA, never ever omit the <shortdesc> tag. These tips specifically target the <shortdesc> tag but they hold good for all introductory paragraphs.

That’s all I have to say today because I wanted this to be a very short write-up. Now, over to you – do write in with your tips 🙂

About the author

Anindita Basu is a writer and editor with IBM, India. She blogs and tweets about technical writing; sometimes, she also tweets on random subjects.

8 Comments

  1. “Automate specific functions to run silently without user inputs by defining Windows services by using the installutil.exe script provided with the installer pack”

    Automate specific functions using Windows services. For these services, run installutil.exe provided with the installer pack.

  2. Now that’s an article! Short, succinct and informative. Keep it up Miss Basu.

  3. Like the way you always illustrate your point with examples. 🙂

  4. It is really helpful, for all levels of experience in Technical Writing

  5. Thats an excellent way to write an article – Short yet the idea is conveyed to the readers and Example for readers to understand.

Comments are closed.