Writing Style

Keep it short and direct

	✅	❌
Lead with what’s important	Run the Parent Segment to load in data.	This Parent Segment needs to be re-run to start loading in your data.
Remove filler text	Delete this folder?	Are you sure you want to delete this folder?

Use active voice often, use passive voice sparingly

	✅	❌
Use active voice for simpler, direct language. People and functions should be described as doing things, instead of having things done to them.	Modify the time frame for this dashboard to show data.	Show data by modifying the time frame for this dashboard.
Use passive voice to soften harsh sentences *limit use	Additional rules were applied to avoid profiles from dropping out of the funnel.	We applied additional rules to avoid profiles dropping out of the funnel.

Write in simple verb forms for present, past, and future tenses.

	✅	❌
Use present tense to describe the conditions that caused the state that still exists.	Cannot rename folder. A folder with the same name already exists.
Use past tense to describe a distinct event that occurred previously. Use simple verb forms	Database details updated. No stage rules created yet	Database details have been updated.No stage rules have been created yet.
Use future tense when describing consequential actions. Avoid using future tense to describe the way a product always acts.	Data for all 10,000 profiles will be permanently deleted.
Avoid phrasal verbs when possible. A phrasal verb combines multiple words to form a single verb phrase.	This model uses your configuration settings.	This model makes use of your configuration settings
Use simple verbs	use	utilize, leverage

Be neutral and instructive

	✅	❌
Don’t blame users	Your email and password do not match.	You entered an incorrect email and password.
Describe the state and offer a solution. Reveal additional information gradually.	No data is available yet. Try rerunning the Parent Segment to load in data.	Error 321032. Data is not available.
Keep an informal, but neutral tone. Write for people, not machines.	Start training your predictive model.	Let’s get started training the features of your logarithmic predictive model!

Optimize for localization

	✅	❌
Avoid directional language e.g. above, below	Items using this segment:	Items below are using this segment:
Avoid negative constructions when possible. Consider whether it’s necessary to tell the user what they can’t do instead of what they can.	Build your Parent Segment to run this journey.	You cannot run this journey because your Parent Segment has not been built yet.
Address the reader directly	you	the user, they
Clarify antecedents	If you use this Parent Segment to populate your profiles, make sure the Parent Segment is running.	If you use this Parent Segment to populate your profiles, make sure it is running.
Avoid colloquialisms, idioms, or slang	It is almost accurate.	It is in the ballpark.
Use qualifying nouns for technical keywords	example.yamlfile	example.yaml