Writing for Logic

Voice and tone

The tone of Logic is professional but conversational. Avoid being stilted and excessively formal, but recognize that users trust us with their critical data.

Avoid using technical jargon in screen text. Not every user is an expert is all aspects of our product. Break this rule when specific technical language is essential for accurately describing an operation. If you must use jargon, link to documentation explaining the concept.

Avoid using slang, memes, and idiomatic language. Some users may find it delightful to “yeet this deployment.” However:

• Many users may not have the cultural context to make sense of the text
• Humor and culture-dependent text can be difficult to translate
• Software has a long shelf life. Jokes which seem fun today may feel awkward or even offensive over time

Pronouns

When referring to the user, use the second person (you, your). Make an exception when referring to content owned by the active user (my deployments, my saved queries).

Use “we” only when referring to the FeatureBase team. Do not use “we” when referring to behaviors of the product.

If we do not know the gender of a person, use gender-neutral pronouns (they, them).

Instructional text

Make liberal use of concise blocks of text to introduce features and explain complex operations. Refer to the Documentation section for guidance on writing screen documentation and when to link to our dedicated documentation sites.

Punctuation

Skip a trailing period when a block of text contains only a single sentence. Skip a trailing period when a sentence ends with a link.

Labels

All labels use sentence case (This is a label). Do not use title case (This is a Label). Of course, if a given name or product name appears in a label, capitalize it as normal.

Do not include a colon at the end of section headers or other grouping labels.

Text on buttons and other clickable controls should emphasize action and should concisely explain what you’re about to do. Text on links should summarize the destination of the link.

Preferred terminology

• Sign in, sign out - Avoid log in, log out
• Deployment - Avoid instance, server, cluster Depending on context, it may be acceptable to use these words to describe a deployment, but they should not be substituted in place of deployment.
• FeatureBase - This is the software which is run on each deployment
• FeatureBase Cloud - This is all the associated control plane tooling (including the UI) to manage FeatureBase deployments in the cloud.

---