This style guide focuses on crafting effective page descriptions and tooltips for a product's user interface. Both elements are crucial for providing clarity and context, helping users navigate and interact with the platform efficiently.
Core Principles
| Principle | What it means |
|---|---|
| Clarity and simplicity | Use straightforward language free of jargon and technical complexity. Keep messages short and to the point. |
| Consistency | Use consistent terminology across all descriptions and tooltips. Follow the same tone, tense, and style throughout the platform. |
| User-centric language | Write from the user's perspective, emphasizing actions or benefits. Avoid internal system terms unless they're user-facing. |
| Accessibility | Ensure text is understandable to all users, including non-native speakers. Use sentence case for readability. |
Page Descriptions
A page description provides a brief explanation of a page's purpose and helps users understand the key actions they can perform there.
Best Practices
| Guideline | What to do |
|---|---|
| Summarize the page's purpose | Focus on what users can accomplish on the page. |
| Limit length | Stick to 1–2 sentences. Avoid overly detailed descriptions. |
| Use action-oriented language | Begin with verbs or phrases describing what the user can do. |
| Avoid repetition | Don't repeat the page title or duplicate other UI elements. |
Examples
| Page | Description |
|---|---|
| Category management page | "Organize and manage your knowledge base categories to structure your content effectively." |
| File upload page | "Upload files to attach them to articles or share with your team." |
| Permission settings page | "Define access permissions for reader groups to control content visibility." |
Tooltips
A tooltip provides additional context or clarification about a specific UI element when users hover over it.
Best Practices
| Guideline | What to do |
|---|---|
| Be concise | Limit tooltips to one short sentence (fewer than 15 words). |
| Add value | Provide information not immediately visible in the UI. Don't repeat labels or descriptions that are already clear. |
| Use present tense | Focus on the current state or action available to the user. |
| Be specific | Tailor tooltips to the functionality of the element. Avoid vague or generic phrases. |
Examples
| Element | Tooltip |
|---|---|
| Allowed domains field | "Enter domains to allow users with matching email addresses to register." |
| Export button | "Download the current data as a CSV file." |
| SEO settings | "Optimize your article for search engines by adding a meta description and keywords." |
Page Descriptions vs. Tooltips
| Aspect | Page descriptions | Tooltips |
|---|---|---|
| Purpose | Provide a summary of the page's purpose. | Offer additional guidance for specific UI elements. |
| Placement | Below the page title or header. | Appears when hovering over a specific element. |
| Length | 1–2 sentences. | A short phrase or single sentence. |
| Tone | Neutral and explanatory. | Contextual and instructional. |
Checklist: Page Descriptions
- Does it clearly explain the purpose of the page?
- Is it short and easy to read?
- Does it guide the user on what they can achieve on the page?
- Does it avoid redundancy with other UI elements?
Checklist: Tooltips
- Does it provide value beyond what's visible in the UI?
- Is it concise and specific to the element, without being overwhelming?
- Does it use present tense?
- Does it avoid repeating the element's label or title?
- Is it free from jargon or complex terminology?
- Is it grammatically correct and properly punctuated?