;
}
};
The choice between active and passive voice is an important aspect of crafting effective and engaging in-app copy.
### Overview
**Active voice** generally enhances the readability and directness of our content, making it easier for users to understand and act upon. It places the subject at the forefront, highlighting who is performing the action. This approach aligns with modern communication practices, promoting a friendly and approachable tone.
**Passive voice**, although less commonly used, has its place in certain contexts where the action or result is more important than the actor, or when we need to be more tactful or indirect.
### Active Voice
Active voice enhances user experience in several key ways:
* **Clarity and Directness**: Active voice makes sentences clearer and more direct. It helps users understand who is performing an action.
* **Engagement**: Active voice is more engaging and friendly, which improves user experience.
* **Efficiency**: Active sentences are usually shorter and more concise, making the copy easier to read and understand.
#### Key pointers
* **Subject-Action-Object Structure**: Ensure that your sentences follow the Subject-Action-Object structure for clarity.\
Example: *The system updates your settings.* (Active) vs. *Your settings are updated by the system.* (Passive)
* **Personal Pronouns**: Use personal pronouns like "you" to make the copy more relatable and engaging.\
Example: *You can reset your password from the settings.* (Active) vs. *The password can be reset from the settings.* (Passive)
* **Command Verbs**: Use command verbs to make instructions clear and direct.\
Example: *Upload your document.* (Active) vs. *Your document should be uploaded.* (Passive)
#### Examples
#### Active voice for instructions
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
Click Submit to save your changes.
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
The Submit button should be clicked to save your changes.
);
}
export default App;
```
**Don't**
#### Active voice for error messages
```tsx lines theme={null}
import { toast } from "@servicetitan/anvil2";
import { useEffect, useRef } from "react";
function App() {
const firstRenderRef = useRef(true);
useEffect(() => {
if (firstRenderRef.current) {
firstRenderRef.current = false;
toast.danger({
title: "We couldn't process your payment.",
message: "Please check your payment method details and try again.",
});
}
}, []);
return ;
}
export default App;
```
**Do**
```tsx lines theme={null}
import { toast } from "@servicetitan/anvil2";
import { useEffect, useRef } from "react";
function App() {
const firstRenderRef = useRef(true);
useEffect(() => {
if (firstRenderRef.current) {
firstRenderRef.current = false;
toast.danger({
title: "Request failed",
message: "Your payment couldn't be processed.",
});
}
}, []);
return ;
}
export default App;
```
**Don't**
### Passive Voice
While active voice is generally preferred for clarity and engagement, there are a few instances where passive voice may be more appropriate.
#### Key pointers
* **Focus on relevance**: Use passive voice when it helps focus on what is most relevant to the user.\
*Example:* An error has occurred. (Passive) vs. The system encountered an error. (Active, but actor might be irrelevant)
* **Soften impact**: Use passive voice to deliver potentially negative information more gently.\
*Example:* Your submission was not accepted. (Passive) vs. We did not accept your submission. (Active, but harsher)
#### Examples
#### Emphasizing the action or result
When the outcome or action itself is more critical than who performed it.
**Reasoning:** The important information is that the account creation was successful, not who created it.
```tsx lines theme={null}
import { toast } from "@servicetitan/anvil2";
import { useEffect, useRef } from "react";
function App() {
const firstRenderRef = useRef(true);
useEffect(() => {
if (firstRenderRef.current) {
firstRenderRef.current = false;
toast.success({
title: "Registration Successful",
message: "Your account has been created.",
});
}
}, []);
return ;
}
export default App;
```
**Do**
```tsx lines theme={null}
import { toast } from "@servicetitan/anvil2";
import { useEffect, useRef } from "react";
function App() {
const firstRenderRef = useRef(true);
useEffect(() => {
if (firstRenderRef.current) {
firstRenderRef.current = false;
toast.success({
title: "Registration Successful",
message: "We created your account.",
});
}
}, []);
return ;
}
export default App;
```
**Don't**
#### Politeness and tact
When delivering bad news or feedback gently.
**Reasoning:** Softens the impact of the denial.
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
Your request has been denied.
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
We denied your request.
);
}
export default App;
```
**Don't**
#### Actor is unknown or irrelevant
When it doesn’t matter who performed the action.
**Reasoning:** Focuses on the action users need to know.
```tsx lines theme={null}
import { toast } from "@servicetitan/anvil2";
import { useEffect, useRef } from "react";
function App() {
const firstRenderRef = useRef(true);
useEffect(() => {
if (firstRenderRef.current) {
firstRenderRef.current = false;
toast.success({
title: "Changes saved.",
message: "You have successfully updated your profile.",
});
}
}, []);
return ;
}
export default App;
```
**Do**
```tsx lines theme={null}
import { toast } from "@servicetitan/anvil2";
import { useEffect, useRef } from "react";
function App() {
const firstRenderRef = useRef(true);
useEffect(() => {
if (firstRenderRef.current) {
firstRenderRef.current = false;
toast.success({
title: "Changes saved.",
message: "Your profile has been successfully updated.",
});
}
}, []);
return ;
}
export default App;
```
**Don't**
