Introductions are a lot like appetizers for a dinner party—they set the stage for the main course. If you put some extra work into the introduction, your readers will be ready for the main course.
When you compose introductions, you typically include these three ingredients:
- Information that defines the topic
- Ideas that capture the interest of the user
- Teasers that tell the reader what to expect from the document
The first two ingredients seem straightforward, but when it comes to telling readers what they can expect, we often rely on repetitive and wooden phrases. The way we handle this raises some questions: Who's doing the talking? Is it authoritative? Is it collaborative? Is this the best way to help users learn and solve their problems?
We'll look at some general tips about introductions but focus on how you tell your readers what to expect from the document. If you prefer to skip the background discussion, you can jump down to the Example lead-ins showing introductions that avoid stock phrases and get to the heart of the page’s subject.
Tips for more active introductions
We have a number of pages on our site that have a heading followed by a This document is about introductory sentence. This sentence often restates the heading. When you read further, there's usually a paragraph that provides a better introduction. We recommend that you avoid using the this document is about and get right to the information the user is looking for.
We’ll look at various alternatives to this type of construction throughout the document. Before you explore those alternatives, consider these ways to write stronger introductions:
- Focus on the user right away. Instead of starting off talking about what the document is about, talk about what the user might want to know or do (think Five questions).
- Ask yourself what information is missing or implied: You might have to define a term or a concept. For example, we have a docs page that focuses on using Gradle, but it never says what Gradle is. Or, in the Observability for Good page, we start off by referencing OfG, but we don’t say what it is.
- Figure out what the real point of the page is and make sure to get it into the introduction. That information is usually contained shortly after the flat “This page is about this” introductory sentence. But you might have to really look at the page to find the emphasis.
To find new ways to reach your reader, explore some alternative approaches to introductions.
Consider some different approaches
What is your document about? The way you answer this question affects your readers and your chance to engage them. If you use the same construction in all of your documents, they may be predictable, but they might also be repetitive to the point that users stop seeing those sentences.
The stock phrase tends to be a barrier to good detail, and it tends to repeat the information already provided in the page title. Often, by moving pertinent information up into the introduction, you can more specifically and interestingly let the reader know what the page is about.
Here’s a sample introduction that summarizes a problem and gets the readers’ attention:
Clogged drains account for 60 percent of calls to professional plumbers. You may be able to solve this problem yourself and avoid the expense.What kind of third sentence could you add to this paragraph to tell readers what the rest of this document is about? The sections below have tables with various options for your third and final plumbing sentence.
Approach 1: Use second person
This option is one of the most engaging for readers because it weaves their needs with the subject of the page.
Mood | Person | Final plumbing sentence | Effect on readers |
|---|---|---|---|
Indicative | Second person singular | You have three options to unclog your drain without a plumber. | This directly identifies the user’s problem and suggests that the information they want is ahead. |
Imperative | Second person singular | To unclog your drain without a plumber, try these three options. | This states the problem, which is followed by a suggestion. |
Consider these three options for unclogging your drain without a plumber. | This reverses the example above by putting the problem second. The verb “consider” engages the reader, but this may have less power because of the delayed statement of the problem. The opening verb could be replaced with any number of verbs: “review,” “evaluate,” “try,” etc. | ||
Read on to learn about three ways to unclog your drain without a plumber. | Although this construction uses second person, the verb itself doesn’t address the reader’s concern and the problem comes second. |
Approach 2: Use third person
This is the tried and true option, but it can become robotic and can be less engaging to readers. A few pitfalls exist with this approach.
Mood | Person | Final plumbing sentence | Effect on readers |
|---|---|---|---|
Indicative | Third person singular | This document contains instructions for three ways to unclog your drain without a plumber. | With this construction, the document itself doesn’t have a voice. The document merely contains the information we (the authorities) put there. |
This document explains three ways to unclog your drain without a plumber. | This is somewhat robotic and gives the document some agency as if it were a speaker. | ||
Indicative | Third person plural | There are three ways to unclog your drain without a plumber. | Marcia Riefer Johnston talks about "There" and "It" as grammatical expletives in her book "Word Up!" She says that we could find ways around these constructions because expletives (not obscenities) have no grammatical function. "It is/was" and "There is/are" add no meaning to the sentence. We use them all the time, but her point is that communication is stronger without them. She suggests you can transform "It is important to tighten your sentences" to "Tighten your sentences." |
Here are three ways to unclog your drain without a plumber. | The construction “Here are” is also an expletive, similar to “There are.” This is certainly clear, but it could have more punch. |
Approach 3: Use first person
When you use the first person we in a procedural document, the we refers to you as the writer along with the reader. You are both going through the steps together.
Tip
This is a different use of we from the more general usage where we can refer to New Relic. You can use we as a substitute for New Relic when it doesn’t refer to the writer and the reader together. For example, “NerdGraph is the API we recommend for querying New Relic data and for performing some specific configurations (learn more about features).”
First person is probably best used in the context of tutorials where a personal relationship is explicit. For example, if you have a blog or a course, and you’re walking users through a procedure. At New Relic, we don’t often have this context, but we may have some cases where this fits.
If you have a context where first person is appropriate, avoid cases where first person sends the message that the company is secretly observing the user or their data. For example, you wouldn’t want to have a first person usage like this: “We see that your agent is out of date. Would you like to update it?”
Mood | Person | Final plumbing sentence | Effect on readers |
|---|---|---|---|
Indicative | First person plural | Here, we look at three ways to unclog your drain without a plumber. | This is somewhat didactic, like a teacher telling the class what she’ll discuss in a session. |
We’ll look at three ways to unclog your drain without a plumber. | This uses a future construction, which gives the reader a sense of what is coming ahead. | ||
Imperative | Third person plural | Let’s look at three ways to unclog your drain without a plumber. | Right away, this tells readers that they are in partnership with the author. They are doing work together. |
The introduction versus “Why it matters” sections
Once you have a range of options to construct your introduction, be careful not to dilute your introduction with a subsequent “Why it matters” section.
To create a more active, user-centered introduction, you might want to include information that you would normally put in a “Why it matters” type of section. You should! We absolutely want users to know why the subject matters to them as soon as possible.
Here is why using “Why it matters” as a section and a heading is a problem:
- Often we wait to share the information that’s most important to a user until the “Why it matters” section. Our goal should be to help users quickly learn what a feature will help them accomplish. So feel free to get rid of that dedicated section if you’re already telling users about this in the introduction or in other sections of the document.
- The value should be coupled with the subject of a document. You should include value statements wherever they make sense. You might have a high-level value in the intro, for example, and then more specific value statements when you discuss another aspect of the subject of the page.
- Don’t use “Why it matters” as a header, regardless. It’s another repetitive phrase that looks like cookie cutter documentation. If you’re dedicating space to addressing this question, create a header that provides information about the value, rather than using the stock “Why it matters” header.
Example lead-ins
Take a look at these lead-ins that avoid stock phrases and get to the heart of the page’s subject. These are rewrites of existing content.
Example 1: Eligibility guidelines
Non-profits and New Relic
This document provides New Relic's Observability for Good program eligibility guidelines for nonprofit, charitable, and NGO organizations.
Exceptions
Many global nonprofit, charity and NGO organizations are eligible for Observability for Good if the organization has a recognized legal status in their respective country equal to 501(c)(3) status under the United States Internal Revenue Code, with certain exceptions. In addition, all organizations must be verified by TechSoup or the local TechSoup partner.Here’s how you might rewrite this:
If your organization is a global nonprofit, charity, or NGO, it might qualify for Observability for Good, a New Relic program that provides expansive, free access to New Relic. To qualify, your organization must have a recognized legal status in your respective country equal to 501(c)(3) status under the United States Internal Revenue Code. And, it must be verified by TechSoup or the local TechSoup partner.
To get started:
1. Check that your organization is not in one of the ineligible categories (link). 2. Submit a New Relic application (link). 3. Get qualified with TechSoup (link).This revision has these changes:
- Defines Observability for Good right away. Get right into the purpose of the page, without having to say what the purpose is.
- Replaces passive first few sentences with more active, second person point of view: “If your organization is a global non-profit, charity, or NGO” instead of “Many global non-profit, charity, and NGO organizations….”
- Keeps the emphasis on “you” the reader and potential beneficiaries of this program.
- Removes the negative “exceptions” and replaces it with specifics about how to qualify and apply.
Example 2: Change your password
This document contains information on New Relic password requirements.
Change your password
New Relic account passwords don't expire. However, users can change their own password and other personal account information anytime.Here is how you might rewrite this:
New Relic account passwords don't expire. However, you can change your own password and other personal account information anytime. You can also request a password reset if you forget your password.This revision has these changes:
- Gets rid of the “this document contains” line and the first H2.
- Starts with the information that will matter the most to a user: passwords don’t expire. You can change your password anytime you want.
- Makes it “you” instead of “users.”
- This is a short page and the introduction can quickly get into the essential info. Plus, the H2s should provide the overview of the info that will be covered.
Example 3: Install the Java agent
This document explains how to install the Java agent using Gradle. For information on manually installing the Java agent, see "Install the Java agent" and "Java agent configuration: Config file."Here is how you might rewrite this:
Gradle is a highly flexible build automation tool that can help you install the Java agent across many instances quickly and consistently.
If you’d like to manually install the Java agent instead, see Install the Java agent and "Java agent configuration: Config file."This revision has these changes:
- Defines Gradle (enables you to automate install).
- Then, when you refer to the manual approach, it’s in direct contrast to the automation tool.
- If you need to clarify that you’re only going to cover a subset of information related to a thing, for example, just one way of many to automate install with Gradle, you could say that: “Here, we provide the most common way to automate your install with Gradle.” Much depends on context.
Example 4: Java agent attributes
New Relic attributes are key-value pairs containing information that determines the properties of an event or transaction. These key-value pairs can help you gain greater insight into your application and annotate the data when you query it. You can also automatically forward user information to New Relic.
Both default and custom attributes are visible in APM transaction traces, distributed traces, and error analytics; APM events and Browser events in dashboards. You can customize exactly which attributes will be sent to each of these destinations.
This document describes the Java agent attributes, details how to enable or disable attributes, and describes the rules the agent follows to determine which attributes to include or exclude for a destination.To improve this, you might keep the first three paragraphs, but add the following to the final paragraph:
Before you start creating custom attributes, familiarize yourself with existing Java agent attributes and how to enable or disable them. In addition, learn the rules for which attributes the agent includes or excludes for a destination.