---
title: "Descriptions"
canonical: "https://documentation.chaos.com/space/DOCSGUIDE/697204745/Descriptions"
format: markdown
---
This page provides details on writing microcopy for descriptions.


## **What is a Description?**

---

A **description **is an information chunk of text, sometimes called ‘body text’. A description can appear as a phrase, sentence, or paragraph. A description could also be a hidden text used by screen readers to explain a heavily visual design. **Tooltips **are considered a description or hint text.


## **Rules**

---

- A description should be no more than **3 lines long**.
- A description line should be up to **40 or 50 characters** long, or **3 to 6 words per line**.
- Separate the information into scannable chunks.
- Place meaningful words where they will be noticed. You must know which words are meaningful.  
For English speakers, the **F-shape scanning** behaviour means that words at the ragged end of sentences are more likely to get noticed.  
The second most effective place to put keywords is at the beginning of sentences, but it is also the most crowded place for the eyes to take in information.
- Avoid asterisks. They reduce trust.
- Avoid fine print. It also reduces trust in the product. (This applies to the UX team)
- Use plain text. (This applies to the UX team)
- When adding hyperlinks, link the entire phrase. (This applies to the UX team)
- Typically, use a **full sentence**.

When a single chunk of text exceeds these rough guidelines, users’ eyes stop lingering on individual words and begin to feel more doubtful. Keeping the text brief and separating ideas into scannable chunks, no larger than the size previously described, makes users feel more confident in their understanding and in their ability to use the experience successfully.


## **Common Patterns**

---

Descriptions are frequently used with titles, buttons or whole experiences.

Some constructions are:

- [to do x, {verb} the {noun}]  
*For example, “To purchase a reduced fare, sign in with a validated account.”*
- [{verbing} the {noun} helps you do X]
- [If X happens, you’ll see Y.]


## **Examples**

---

Some common examples of descriptions can be found in the panels in Envision. These descriptions don’t follow the guidelines, which makes them harder to understand. For example, the Materials description could be improved as follows:

`The Material panel lists all materials`  
`in your project.`


![TechGuide_Descriptions_Onboarding.png](media://214b3783-a0da-40a0-9ead-1b4d258eaf85)


All parameter tooltips, such as the Ground Albedo tooltip in Vantage. The following tooltip exceeds 50 characters, so it would be better to split the text into two lines.


![TechGuide_Descriptions_Tooltips.png](media://9d405691-5999-42ec-ad2f-ea6e029ad7d5)