Adds UI text guidance to style guide (#2495)

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>
This commit is contained in:
Nate Bower 2023-01-25 13:58:52 -05:00 committed by GitHub
parent 985d31b8f7
commit 4c7cd0cc1e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 84 additions and 0 deletions

View File

@ -179,6 +179,8 @@ The following table lists acronyms that you don't need to spell out.
- Use italics for the titles of books, periodicals, and reference guides. However, do not use italics when the title of a work is also a hyperlink.
- Reference images in the text that precedes them. For example, "..., as shown in the following image."
### Links
- **Formal cross-references**: In most cases, a formal cross-reference (the title of the page you're linking to) is the preferred style because it provides context and helps readers understand where they're going when they choose the link. Follow these guidelines for formal cross-references:
@ -295,6 +297,78 @@ Here are two styles you can use for topic titles:
* Field types
* Security analytics
## UI text
Consistent, succinct, and clear text is a critical component of a good UI. We help our users complete their tasks by providing simple instructions that follow a logical flow.
### UI best practices
* Follow the OpenSearch Project [naming conventions, voice, tone, and brand personality traits](#naming-conventions-voice-tone-and-brand-personality-traits) guidelines.
* Be consistent with other elements on the page and on the rest of the site.
* Use sentence case in the UI, except for product names and other proper nouns.
### UI voice and tone
Our UI text is people oriented and focused on empowering the user directly. We use language that is conversational, welcoming, engaging, and open and that emphasizes what the user can do with OpenSearch rather than what tasks OpenSearch can perform. The overall tone is knowledgeable but humble, informal but authoritative, informative but not dry, and friendly without being overly familiar.
We talk to readers in their own words, never assuming that they understand how OpenSearch works. We use precise technical terms where appropriate, but we avoid technical jargon and insider lingo. We speak to readers in simple, plain, everyday language.
For more information, see [Voice and tone](#voice-and-tone) and [Brand personality traits](#brand-personality-traits).
### Writing guidelines
UI text is a critical component of a user interface. We help users complete tasks by explaining concepts and providing simple instructions that follow a logical flow. We strive to use language that is consistent, succinct, and clear.
#### What's the purpose of UI text?
UI text includes all words, phrases, and sentences on a screen, and it has the following purposes:
* Describes a concept or defines a term
* Explains how to complete a task
* Describes the purpose of a page, section, table, graph, or dialog box
* Walks users through tutorials and first-run experiences
* Provides context and explanation for individual UI elements that might be unfamiliar to users
* Helps users make a choice or decide if settings are relevant or required for their particular deployment scenario or environment
* Explains an alert or error
#### Basic guidelines
Follow these basic guidelines when writing UI text.
##### Style
* Keep it short. Users dont want to read dense text. Remember that UI text can expand by 30% when its translated into other languages.
* Keep it simple. Try to use simple sentences (one subject, one verb, one main clause and idea) rather than compound or complex sentences.
* Prefer active voice over passive voice. For example, "You can attach up to 10 policies" is active voice, and "Up to 10 policies can be attached" is passive voice.
* Use device-agnostic language rather than mouse-specific language. For example, use _choose_ instead of _click_ (exception: use _select_ for check boxes).
##### Tone
* Use a tone that is knowledgeable but humble, informal but authoritative, informative but not dry, and friendly without being overly familiar.
* Use everyday language that most users will understand.
* Use second person (you, your) when you address the user.
* Use _we_ if you need to refer to the OpenSearch Project as an organization; for example, "We recommend…."
##### Mechanics
* Use sentence case for all UI text. (Capitalize only the first word in a sentence or phrase as well as any proper nouns, such as service names. All other words are lowercase.)
* Use parallel construction (use phrases and sentences that are grammatically similar). For example, items in a list should start with either all verbs or all nouns.<br>
**Correct**
Snapshots have two main uses:
* Recovering from failure
* Migrating from one cluster to another<br><br>
**Incorrect**
Snapshots have two main uses:
* Failure recovery
* Migrating from one cluster to another<br><br>
* Use the serial (Oxford) comma. For example, “issues, bug fixes, and features”, not “issues, bug fixes and features”.
* Dont use the ampersand (&).
* Avoid Latinisms, such as _e.g._, _i.e._, or _etc._ Instead of _e.g._, use _for example_ or _such as_. Instead of _i.e._, use _that is_ or _specifically_. Generally speaking, _etc._ and its equivalents (such as _and more_ or _and so on_) arent necessary.
## Special considerations for blog posts
Blog posts provide an informal approach to educating or inspiring readers through the personal perspective of the authors. Brief posts generally accompany service or feature releases, and longer posts may note best practices or provide creative solutions. Each post must provide a clear community benefit.

View File

@ -262,6 +262,12 @@ Exception: *Execution* is unavoidable for third-party terms for which no alterna
**frontend (n., adj.)**
Use frontend as an adjective and a noun. Do not use front end or front-end. Do not make frontend possessive except as part of a compound noun, such as frontend system.
## G
**geopoint**
**geoshape**
## H
@ -620,6 +626,10 @@ Never hyphenate. Use _time out_ as a verb (“The request will time out if the s
**time frame**
**time-series data**
Data that's provided as part of a metric. The time value is assumed to be when the value occurred.
**timestamp**
**time zone**