# Tone & Voice (/foundations/tone-and-voice)



Especially in the age of AI, it's important that we speak with a clear, distinct voice. These guidelines outline how we communicate with others using words, both in our product copy and across our sales and marketing activities.

Use this as a starting point when writing for HASH and its developer-facing brands. Adapt examples to the actual product and situation, and check claims with the person responsible for the feature or communication.

## Our voice [#our-voice]

Our voice should make HASH recognizable through what we explain, the details we choose, and the care we take with the reader's time. We sound informed, approachable, and candid.

| Quality  | What it means in practice                                                                                                                 |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Specific | Name the task, the result, and any limits. A concrete example is more useful than a broad promise.                                        |
| Human    | Address the reader directly. Use familiar words and natural contractions. Explain something as you would to a colleague who is new to it. |
| Useful   | Give the information someone needs for their next decision or action. Put supporting detail where they can find it.                       |
| Credible | Match confidence to evidence. Distinguish what is available today from a proposal, preview, or future plan.                               |

Distinctive writing comes from an informed point of view. Describe the problem we understand, the decisions behind our approach, and what that means for the reader. Stock enthusiasm and interchangeable claims make it harder to tell why HASH matters.

## Write for the audience [#write-for-the-audience]

The audience changes the explanation, examples, and level of detail. The same care and accuracy should be apparent across every brand.

### HASH and business audiences [#hash-and-business-audiences]

The **hash.ai site and general HASH-branded communications** speak to a broad audience, including business users, leaders, and people evaluating HASH. Begin with the task they recognize and the outcome they need. Explain technical concepts when they help someone make a decision.

Use examples from the reader's work. In sales material, connect a capability to the problem discussed with that customer. Make the scope of a claim clear, including setup, availability, and any work the customer would need to do.

### Developer audiences [#developer-audiences]

**hash.dev and our developer-facing brands, including Petrinaut, SemType, and hgres**, speak to developers, researchers, and other technical readers. They often need exact behavior, technical tradeoffs, and enough detail to build or evaluate something themselves.

Use established technical terms when they add precision. Define unfamiliar project-specific terms, preserve exact API and package names, and show examples that match the documented version. Explain constraints and failure cases alongside the expected result. Respect expertise while allowing for someone encountering this project for the first time.

### The same fact, explained differently [#the-same-fact-explained-differently]

These examples describe an illustrative product behavior. Use them only when the implementation supports the claim.

| Audience      | Example                                                             |
| ------------- | ------------------------------------------------------------------- |
| Business user | “You can see when a record changed and what it said before.”        |
| Developer     | “The record history includes each saved version and its timestamp.” |

The developer version supplies a more exact model. Both versions should describe the same behavior; changing the audience must never change the facts.

## Adapt the tone to the situation [#adapt-the-tone-to-the-situation]

**Voice** is our consistent way of communicating. **Tone** is how we adjust it to the reader's situation. Consider what someone is trying to do, what they already know, and what is at stake.

| Situation                     | Tone                      | Example                                                                                                 |
| ----------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Learning or exploring         | Welcoming and explanatory | “Start with a small example, then adapt it to your data.”                                               |
| Completing a routine action   | Brief and calm            | “Changes saved.”                                                                                        |
| Recovering from a failure     | Direct and helpful        | “We couldn't save your changes. Try again.”                                                             |
| Facing a consequential action | Explicit and measured     | “Delete this workspace? This permanently deletes its projects.”                                         |
| Evaluating a proposal         | Confident and specific    | “The proposal covers these three workflows. This section explains the assumptions behind the estimate.” |

Match each message to the actual state. Say that work is saved or recoverable only when it is. Use warmth where it helps, and keep humor out of errors, access restrictions, and potentially irreversible actions. A repeated success message rarely needs a celebration.

## Product copy [#product-copy]

Write for the task someone is doing at that moment. Use the same name for a thing in navigation, buttons, help text, and notifications.

* **Headings** explain the task or current state. “Invite people” is easier to act on than “User management.”
* **Buttons** name the action and, where useful, its object: “Save changes,” “Create project,” or “Delete workspace.” Use “Continue” when the surrounding step makes the destination clear.
* **Field labels** remain visible while someone types. Put required formats and useful constraints in help text; placeholders are examples, not replacements for labels.
* **Empty states** explain why the view is empty and offer the relevant next step. Distinguish a new account, no search results, and unavailable data.
* **Errors** explain what failed and what someone can do. Add a cause only when it is known. Preserve entered work where possible, and describe what happened to it accurately.
* **Destructive confirmations** identify what will be affected and whether the action can be undone. Use the same action verb on the confirming button.

### Make the next step clear [#make-the-next-step-clear]

The following are illustrative rewrites, not claims about current product behavior.

| Less useful          | More useful                                         | Why                                               |
| -------------------- | --------------------------------------------------- | ------------------------------------------------- |
| “An error occurred.” | “We couldn't save your changes. Try again.”         | Identifies the failed action and a recovery step. |
| “Invalid input.”     | “Enter an email address, like `name@example.com`.”  | Explains the expected value.                      |
| “Nothing here!”      | “No projects yet. Create a project to get started.” | Explains the state and offers a next action.      |
| “Are you sure?”      | “Remove Alex from this workspace?”                  | Names the consequence of the decision.            |

Pair copy with the behavior described in [Forms](/patterns/forms), [Error handling](/patterns/error-handling), [Empty states](/patterns/empty-states), and [Notifications and messaging](/patterns/notification-messaging).

## Sales and marketing [#sales-and-marketing]

Help someone understand whether HASH is relevant to them. A useful explanation connects a recognizable problem, a specific capability, and evidence of the result.

Start with what matters to that reader. Follow with how the product helps, the evidence behind the claim, and a useful next step. A headline can be expressive; the explanation beneath it must make the meaning concrete.

* Describe the workflow or capability behind a claim. Replace general praise with a demonstration, customer example, or supported comparison.
* Put figures in context. For a performance or time-saving claim, include the measurement conditions, comparison, and limits needed to interpret it.
* Use customer quotes faithfully and with permission. Keep the context that changes their meaning.
* Keep current availability, previews, and plans distinct. Avoid promising delivery dates or outcomes that have not been agreed.
* Make calls to action match their destination. “View the example” should open the example; “Book a demo” should lead to booking.

For example, a demo invitation can say: “You mentioned that comparing versions takes time. We can walk through that workflow together.” Use it when it reflects the conversation and what the demo can show. Avoid sending a generic promise dressed up as a personal observation.

## AI-assisted writing and AI features [#ai-assisted-writing-and-ai-features]

Use AI to explore wording, organize material, and test whether an explanation is understandable. The person publishing remains responsible for its accuracy, audience fit, and voice.

Give the model the audience, task, approved facts, and examples of existing copy. Review names, numbers, links, quotations, and product claims against their sources. Remove repetitive summaries and generic excitement that add length without helping the reader.

When writing about an AI feature, describe the specific action it performs and what the person should check. “Draft ready. Review the figures before sharing” is more useful than claiming the result is automatically trustworthy. Use words such as “verified” only when a defined check has actually happened, and explain its scope where needed.

Keep uncertainty visible when it affects a decision. Distinguish generated suggestions from saved changes or completed actions. Explain a limitation near the result it qualifies, and give a useful next step.

## Language and mechanics [#language-and-mechanics]

Use these defaults unless the product or document has an established convention that better serves its audience.

* Use sentence case for headings, labels, and buttons. Preserve brand names and exact technical identifiers.
* Prefer active sentences that identify who does what. “You can invite a teammate” is easier to follow than “Invitations can be issued.”
* Use “you” for the reader and “we” when HASH takes responsibility. Avoid switching between different speakers in the same interaction.
* Keep one term for each concept. Explain an acronym on first use when the audience may not know it.
* Choose inclusive language. Avoid idioms, cultural assumptions, and wording that makes a task sound easy to someone who may be struggling.
* Make links meaningful out of context. Use “View installation instructions” rather than “Click here.” Refer to the named control instead of relying on its position or color.
* Use simple punctuation. Use full stops in complete messages and descriptions, and usually omit them from short labels and buttons. Use exclamation marks sparingly.
* Make dates, units, and quantities unambiguous. Use the reader's locale where the product supports it; preserve exact values and formats in technical examples.

Follow the naming and usage guidance on the relevant [brand page](/brands). For interface text, also check [Typography](/foundations/type) and [Accessibility](/foundations/accessibility).

## Before publishing [#before-publishing]

Read the copy in the place it will appear, with the actual heading, controls, and surrounding content.

1. Identify the reader and the question or task this text answers.
2. Check every factual claim, example, and implied promise against the current product or approved source.
3. Put the information needed for the next action first. Remove repetition that does not help the reader.
4. Check terminology, names, links, and capitalization against nearby copy.
5. Review difficult states as carefully as the happy path: failure, delay, empty results, and irreversible actions.
6. Read it aloud, then check it in context at a narrow width. Ask someone unfamiliar with the task to explain what they would do next.