XMTP content style guide

Learning objective: As an XMTP Labs employee, I want to understand best practices for writing clearly and consistently about XMTP so that the content I publish can help our team and the XMTP community build a shared understanding of XMTP that is accurate and meaningful.

A large part of our communication takes the form of written communication. Using shared style guidance to inform our writing helps us provide consistent and clear content for our readers.

If you have any questions about content style, contact J-Ha.

Technical content style

When writing technical documentation and blog posts, follow the Google developer documentation style guide for technical content style guidance. You can also use this style guide when writing internal documentation.

You might find these sections of the Google developer documentation style guide particularly useful:

• Headings and titles: Long story short, use sentence case for headings and titles.

• Word list: Use this list when unsure of which word to use in your technical writing. For example, should I use "above", "higher", or "later" when referring to a release version number? (Use "later".) You can also find out how to format a word. For example, should I use "open source" or "open-source"? (Use "open source".)

• Write inclusive documentation

If you can't find the guidance you need in the Google developer documentation style guide, follow the Microsoft Writing Style Guide.

For XMTP-specific word use, see Word list.

Nontechnical grammar and punctuation

If you need guidance about grammar and punctuation for nontechnical terms, follow the Chicago Manual of Style.

Contact J-Ha about access.

Nontechnical spelling

If you need guidance about the spelling of a nontechnical term, follow the Merriam-Webster Dictionary.

Plain language

Sound boring? Just the opposite! There are few things more impactful than writing in language that your audience can understand the first time they read it.

Plainlanguage.gov is a great place to learn how to write plainly. From the website:

Language that is plain to one set of readers may not be plain to others. Material is in plain language if your audience can:

• Find what they need
• Understand what they find the first time they read or hear it
• Use what they find to meet their needs

Here's their handy list of plain alternatives to complex language: Use simple words and phrases.

The US government is so dedicated to using plain language in government documents President Obama signed the Plain Writing Act of 2010 into law on October 13, 2010.

Word list

This list provides guidance for using certain words and phrases when writing about XMTP.

info

This word list is not meant to be a glossary. For some XMTP terms and definitions, see XMTP Protocol Definitions. XMTP Engineering developed these definitions to help provide a shared understanding of the terminology and goals of the XMTP system.

app / application

Use app instead of application when referring to software for users, especially in the context of mobile or web software.

It's OK to use application when you need to convey a sense of greater complexity. For example, when referring to enterprise software or to a level of abstraction, such as application-level or the application layer.

When referring to an app built with XMTP, use client app.

blockchain account

info

This usage guidance isn't perfect just yet. It is fluid and will evolve as we learn more as a team and community.

Per Ethereum.org:

An Ethereum account is an entity that can send transactions and has a balance.

From this definition, we derive blockchain account as a slightly more generic term for an abstraction that refers to a public and private key pair that can send transactions and reference a balance stored on a blockchain. We use blockchain account to refer to what can send and receive messages using XMTP network. We use blockchain account instead of Ethereum account to convey that XMTP is chain-agnostic.

For example, the headline of xmtp.org reads:

Build with XMTP to send alerts, announcements, and messages between blockchain accounts

A colloquial yet potentially misleading synonym for blockchain account is wallet. We discourage using wallet to refer to a blockchain account, especially in more formal contexts such as XMTP documentation. For example, instead of wallet messaging, use blockchain account messaging.

While wallet messaging might be easier to say, for people who are newer to web3 and don't know the colloquialism, wallet messaging can evoke the inaccurate concept of an XMTP inbox embedded in a specific wallet app, instead of the accurate concept of an XMTP inbox that is universally accessible anywhere you can log in with a blockchain account.

Using wallet is OK when used in wallet app.

blockchain address

info

This usage guidance isn't perfect just yet. It is fluid and will evolve as we learn more as a team and community.

Per Ethereum.org:

An Ethereum account has an Ethereum address, like an inbox has an email address. You can use this to send funds to an account.

From this definition, we derive blockchain address as a slightly more generic term describing the same concept: A blockchain account has a blockchain address like an inbox has an email address. You send funds to a blockchain account using a blockchain address.

We discourage using wallet address to refer to a blockchain address, especially in more formal contexts such as XMTP documentation. Instead of wallet address, use blockchain address. This is because the concept of a wallet address does not actually exist in EVM. Using wallet address in the context of XMTP is a source of ambiguity because it can be incorrectly interpreted as meaning that XMTP is integrated with wallet apps (like WalletConnect actually is).

build with

Don't use integrate with.

Correct	Incorrect
✅ Build with XMTP to provide blockchain account messaging in your app.	⛔️ Integrate with XMTP to provide blockchain account messaging in your app.

can

Use to mean ability or possibility.

If you mean possibility and can sounds too certain, use might.

If you mean permission, use may.

For example:

• Messages can incur fees. (ability, possibility)
• Messages might incur fees. (less certain possibility)
• Messages may incur fees. (permission)

client

When referring to an app built with XMTP, use client app. Don't use the standalone form app or client.

When referring to the client embedded in a client app, use app client.

When referring to the client running on a network node, use network client.

When referring to XMTP app clients and XMTP network clients, use the indefinite article an. For example, use “an XMTP app client”, not “the XMTP app client”.

Correct	Incorrect
✅ XMTP network clients retrieve encrypted messages from storage and deliver them to app clients.	⛔️ XMTP nodes retrieve encrypted messages from storage and deliver them to clients.
✅ Developers build apps that embed an XMTP app client.	⛔️ Developers build apps that embed the XMTP app client.

composes

A user composes a message in a client app.

To learn more, see Writing about how messages move using XMTP

customer

Don't use. Because XMTP is open source, permissionless, trustless, and progressively decentralized, there is no customer who buys goods or services from XMTP.

Instead, name the persona that works with or uses XMTP.

decentralized

Refers to the state of decentralization of the XMTP network. Don’t use to describe the current state of the XMTP network. Currently, the XMTP network is not decentralized because XMTP Labs runs all of the XMTP nodes and network clients that provide the XMTP network.

We aim to publish a phased decentralization roadmap in Fall 2022.

See also: progressive decentralization

fetches

Don't use. Use retrieves.

To learn more, see Writing about how messages move using XMTP

in order to

Remove this phrase to reduce wordiness. Removing this phrase usually doesn’t result in a loss of meaning.

Correct	Incorrect
✅ Describe prerequisites a user needs to meet to achieve their goal.	⛔️ Describe prerequisites a user needs to meet in order to achieve their goal.

individual

We use individual when we need to distinguish between the following user types:

• Individuals
  A single externally owned account (EOA) that sends or receives messages. When we don't need to immediately distinguish these user types, we use participant, or if possible, more specifically sender or recipient.
• Teams
  Groups of EOAs that send or receive messages as a single identity.

integrate with

Don't use. Use build with.

Correct	Incorrect
✅ Describe prerequisites a user needs to meet to achieve their goal.	⛔️ Describe prerequisites a user needs to meet in order to achieve their goal.

interoperability

In the XMTP context, when we talk about interoperability, we're usually referring to one of the following scenarios:

1. Interoperabiity of message data, which can be presented across client apps
2. Interoperability of message presentation, which can be handled consistently across client apps
3. Different signer types (e.g. ed25519 and EVM) will be able to message each other. This scenario creates an illusion of interoperability between chains. Because these signer types are accessed through wallet apps, and wallet apps connect to chains, "a user of a client app that is connected to Solana can communicate with a user of a client app that is connected to Ethereum." While this is true, XMTP doesn't care about or use those chain connections. They're just an artifact of the way dapps access signers through wallet apps that connect to chains.

With these scenarios in mind, consider these usage guidelines:

Correct	Incorrect
✅ XMTP enables interoperability of message data, which can be presented across client apps.	⛔️ XMTP enables interoperability of message data across EVM chains.

key bundle

In XMTP, there are two types of key bundles, a public key bundle and a private key bundle. Be sure to specify which key bundle you mean.

To refer to them collectively, use public and private key bundles.

To learn more, see XMTP key bundles.

key pair

A combination of a public key that is used to encrypt data and a private key that is used to decrypt data. Don't use key-pair.

key-value pair

A pairing that specifies a value for a variable (as in configuration files).

Don't use:

• key value
• key/value pair

litepaper

Not lightpaper. Different from whitepaper.

may

Use to mean permission.

If you mean ability or possibility, use can. If can sounds too certain, use might.

For example:

• Messages can incur fees. (ability, possibility)
• Messages might incur fees. (less certain possibility)
• Messages may incur fees. (permission)

might

Use to mean possibility.

If you mean ability or a more certain possibility, use can. If you mean permission, use may.

For example:

• Messages can incur fees. (ability, possibility)
• Messages might incur fees. (less certain possibility)
• Messages may incur fees. (permission)

node

A computer running XMTP network client software. See client.

On first reference in a paragraph, use XMTP node to ensure that people understand which node you’re talking about. For example, depending on surrounding context in your content, people may be unsure of whether the node is in the XMTP network or another network or blockchain.

offer

Avoid using in a way that centers the content on what XMTP does. Rewrite the content to focus on what developers can do with XMTP.

For example:

Correct	Incorrect
✅ Developers can easily integrate messaging using XMTP.	⛔️ We offer developers an easy way to integrate messaging.

To learn more, see Active voice.

on top of

Don't use. Use built with.

open

When referring to software released under a license in which anyone can use, study, change, and distribute the software and its source code, use open source. Don't use the standalone form open.

See also: permissionless.

participant

Use to refer to the entities that can send or receive messages in a specific DM conversation, group chat, or announcements channel topic.

When possible, refer to a more specific participant type:

• To refer to an entity sending a message in a specific DM conversation, group chat, or announcements channel topic, use the more specific sender.

• To refer to an entity receiving a message in a specific DM conversation, group chat, or announcements channel topic, use the more specific recipient.

A participant is different from a user in that topics have participants, but not users. Client apps and the XMTP network have users, but not participants.

Don't use parties to refer to participants.

partner, partnership

Don't use because these terms convey a centralized voice. Use collaborator or collaboration, or contributor or contribution instead.

permissionless

Anyone, both users and developers, for example, can participate in XMTP without permission, or authorization, from a governing body. Everyone has equal access to participate, and no one gets excluded.

For example, here are some contexts in which you might use permissionless to describe aspects of XMTP:

• The XMTP SDK is permissionless in that anyone can access, develop with, and contribute to the SDK.
• The XMTP network is permissionless in that any app built with XMTP can connect to the XMTP network to send and receive messages on behalf of the app’s users.
• In its future decentralized state, the XMTP network will also be permissionless in the sense that anyone will be free to operate a node running a network client and have it join the XMTP network. As long as the XMTP protocols allow it, anyone can use the XMTP network to do anything they want within the network.

See also: open

plain text vs plaintext

Be sure to use the correct word:

• plain text: Text without formatting (without bold, italic, color, etc.)
• plaintext: Unencrypted text

presents

A client app presents a message to a user

To learn more, see Writing about how messages move using XMTP

progressive decentralization

Refers to the strategy to progressively decentralize the XMTP network.

Specifically, node operation will be progressively decentralized, first by including only a benevolent set of operators (the first of which being XMTP Labs) and later decentralizing through permissionless and incentivized node operation.

We aim to publish a phased decentralization roadmap in Fall 2022.

proof-of-stake, proof-of-work

For usage guidance, see https://ethereum.org/az/contributing/style-guide/#proof-of

protocol

info

This usage guidance isn't perfect just yet. It is fluid and will evolve as we learn more as a team and community.

When using to refer to XMTP, always clarify which protocol you are referring to. For a work-in-progress list of protocols in XMTP, see the XMTP Layers diagram (WIP).

If you want to refer to all of the protocols collectively, use XMTP.

Correct	Incorrect
✅ The network protocol design also accommodates asynchronous offline communication and secure storage of messages.	⛔️ The protocol design also accommodates asynchronous offline communication and secure storage of messages.

publishes

Don't use. Use relays.

To learn more, see Writing about how messages move using XMTP

receives

A user receives a message from another user

To learn more, see Writing about how messages move using XMTP

recipient

Use to refer to an entity that can receive messages in a specific DM conversation, group chat, or announcements channel topic.

Don't use receiver.

relays

A node relays a message to other nodes

To learn more, see Writing about how messages move using XMTP

retrieves

A client app retrieves a message from the network

To learn more, see Writing about how messages move using XMTP

sender

Use to refer to an entity that can send messages in a specific DM conversation, group chat, or announcements channel topic.

sends

A user sends a message to another user

To learn more, see Writing about how messages move using XMTP

service

As in web service. Don't use. Web services don't exist in the web3 context.

should

Don't use, except in contexts where the term is explicitly defined, such as in RFC specs.

To learn more, see Subjunctive mood.

submits

A client app submits a message to the network

To learn more, see Writing about how messages move using XMTP

subscribes

A client app subscribes to a direct message topic.

to learn more, see Writing about how messages move using XMTP

team

info

This usage guidance isn't perfect just yet. It is fluid and will evolve as we learn more as a team and community.

A group of externally owned accounts (EOAs) that send or receive messages as a single identity.

See also: individual

trustless

The XMTP network is trustless in that it allows participants to interact with it without the oversight of a trusted third party, or authority. Instead of using trusted third parties, the XMTP network aims to use incentives and economic mechanisms to encourage participants to interact in a way that supports the health of the network.

Example usage:

The XMTP network is permissionless in that anyone can choose to participate in it, from users to developers. The XMTP network is trustless in that anyone who chooses to participate can do so without the oversight of a trusted third party.

user

Refers to a user of an app built with XMTP, in a general sense. It can also refer more broadly to the set of people registered on the XMTP network.

To refer more specifically to the entities that can send or receive messages in a specific DM conversation, group chat, or announcements channel topic, use participants.

A user is different from a participant in that client apps and the XMTP network have users, but not participants. Topics have participants, but not users.

If you need to specify the end user of a product versus another type of user of a product, such as an administrator user or system operator user, use end user (noun) or end-user (adjective).

utilize

Don't use. Use use.

wallet

info

This usage guidance isn't perfect just yet. It is fluid and will evolve as we learn more as a team and community.

When referring to a public and private key pair that you can use to send transactions and reference a balance stored on a blockchain, don't use wallet, use blockchain account.

When referring to an address you can use to send funds to a blockchain account, don't use wallet address, use blockchain address.

When referring to a product that lets you manage your blockchain account, view your account balance, send transactions, sign requests and transactions from web3 apps, and more, don't use wallet, use wallet app.

we

When writing about XMTP, using the word we can get complicated. Who is we? XMTP the technology? XMTP Labs the company? XMTP contributors? An even more general group of people?

A good rule of thumb is to use we only when a more specific noun is not applicable. Use the more specific noun upon first reference to set the context. You can then use we on subsequent references as long as its connection to the specific noun remains clear to the reader.

Being mindful and specific in how we use we helps us to:

• Avoid writing about XMTP Labs in a way that portrays XMTP Labs as a centralized owner or controller of XMTP, the technology.
• Avoid writing about XMTP Labs in a way that can be perceived as intentionally obscuring when XMTP Labs is indeed leading an effort affecting XMTP, the technology.

See these examples of before-and-after we usage:

Before	After	Explanation
We believe this limitation hinders the widespread adoption and usability of web3 technologies.	We the authors of this litepaper believe this limitation hinders the widespread adoption and usability of web3 technologies.	This is a belief expressed by the authors of the XMTP litepaper, so it should be attributed as such. This is not a belief expressed by people in general (we), nor the XMTP community, nor XMTP Labs. On a related note, there is rarely a need for XMTP Labs to speak on behalf of XMTP contributors or the XMTP community. If XMTP contributors, for example, have something to say, it should be attributed to XMTP contributors.
Email and its protocol SMTP have served us dutifully since the beginning of the internet, and as we embark on this new journey that web3 has opened the door to, it's time to bring email's essence along. It's time we build XMTP.	Email and its protocol SMTP have served people dutifully since the beginning of the internet, and as we embark on this new journey that web3 has opened the door to, it's time to bring email's essence along. It's time to build XMTP.	Us could probably stand as-is, but changing it to people makes it even clearer. The we works as-is because it refers back to people. We also works as a reference to a general group of humans on this journey. Removing the last we removes the need to clarify who will do the building and creates an open invitation to build.
We address this limitation with XMTP by giving web3 participants the ability to send and receive messages that are associated with the sender or recipient's blockchain account.	XMTP addresses this limitation by giving web3 participants the ability to send and receive messages that are associated with the sender or recipient's blockchain account.	Changing the we to XMTP makes it clear what is addressing the limitation.
In the future, we will explore additional parameters for message extensibility beyond content and context. Specifically, we will define parameters that affect message deliverability, such as message expiration, receiving latency, and other features.	In the future, XMTP contributors might explore additional parameters for message extensibility beyond content and context. Specifically, contributors might choose to define parameters that affect message deliverability, such as message expiration, receiving latency, and other features.	Reworded to narrow the we down to a more specific group of actors. Also changes the "will" to "might" as XMTP Labs does not dictate what XMTP contributors will do.

web3

Use web3, not Web3, web 3.0, or Web 3.0.

The use of web3 reflects the web3 community's intentional move away from Web 2.0 patterns, represented by the lowercasing of the "w" and removal of the space and the ".0".

web3 identity

XMTP works with Ethereum accounts and other web3 identities that client apps built with XMTP can derive from Ethereum accounts, such as ENS names and Lens profiles.

ENS names and Lens profiles are examples of web3 identities. Web3 identities enable portability of data, such as Lens profile posts or XMTP messages, by not tying a participant's data to an account that works with only one client app, such as Facebook or Twitter account. Rather, web3 identities tie a participant's data to a more foundational identity layer, such as a blockchain account. Because XMTP works with web3 identities tied to blockchain accounts, your XMTP inbox is universally accessible anywhere you can log in with a blockchain account.

As so elegantly stated by a tweet from Lens Protocol:

Pro Tip: If you don't agree with a frontend's policy that's powered by Lens, your profile is portable -- you can move to another platform powered by Lens without losing your profile or social graph :)

To learn more, see Mapping the Web3 Identity Landscape.

whitepaper

Not white paper. Different from litepaper.

What is a whitepaper?

• A whitepaper provides persuasive and factual evidence that a particular proposal is a viable method of solving a problem.

• A whitepaper helps readers make informed decisions about their actions based on the proposal. Will they invest in the project? Will they promote it? Will they adopt or contribute to it?

• A whitepaper is not a user manual or other technical documentation meant to provide support for the offering described in the proposal.

would

Don't use. Avoid subjunctive mood.

To learn more, see Subjunctive mood.

XMTP identity

On first reference in a paragraph, use XMTP identity to ensure that people understand which type of identity you’re talking about. For example, depending on surrounding context in your content, people may be unsure of whether the identity is an XMTP identity, web3 identity, or yet another type of identity.

XMTP network

Not XMTP Network. Not productized.

When to use on the XMTP network vs. *in** the XMTP network:

• Encrypted keys are stored on the XMTP network
• You can run a node in the XMTP network

Active voice

Write in the active voice whenever possible and appropriate. Why?

“In passive voice, it's easy to neglect to indicate who or what is performing a particular action. In this kind of construction, it's often hard for readers to figure out who's supposed to do something (such as the reader, the computer, the server, or a user).

Sometimes, you might need to write in passive voice because you can’t or don’t want to identify the actor. However, aim to make using passive voice in your content a conscious decision, not an oversight.

If you aren’t used to writing in active voice, you might find that it takes some practice to recognize when you’ve slipped into passive voice! To learn more about writing in active voice, see Active voice in the Google developer documentation style guide. For even more detailed guidance, see Active voice in the Google Technical Writing One course.

Capitalization

Use judiciously when it comes to the naming parts of XMTP. Use only for things we want to officially productize, which will likely be few. For example, we don't even capitalize and productize XMTP network. Check with leadership before using capitalization to indicate productization.

Use sentence case capitalization in headings and titles.

Cast of characters

Sometimes we need to use a cast of characters to help explain a flow or use case.

For example, see how this Message encryption flow uses Amal as the message sender character and Bola as the message recipient character. Using named characters can help people more easily understand flows involving multiple individuals.

XMTP technical documentation currently uses these three named characters:

• Amal
• Bola
• Cruz

These names come from the Example person names in the Google developer documentation style guide, which is the style guide we follow for technical documentation. These names are meant to reflect the diversity that exists in the real world and are an intentional departure from the Alice and Bob cast of characters.

Additionally, these names are gender-neutral, which enables the documentation to use the gender-neutral singular pronouns they, their, and theirs. We use gender-neutral pronouns based on guidance from the Google developer documentation style guide.

Contractions

Because XMTP content aims to be approachable, it's OK to use contractions such as "isn't", "don't", and "can't".

For more details, see Contraction in the Google developer documentation style guide.

Forward-looking statements

Technical documentation must not make forward-looking statements. For example, don’t say, “In the future, we will...” or “We plan to...”

Technical documentation is a legal document that describes what a user can do, not what a user might be able to do in the future.

If you need to publish content that makes forward-looking statements, you can do it in a blog post or in a document published to the “Vision” section of xmtp.org.

See also: Present tense

Headings and titles

Use sentence case.

Don't put a period at the end of a heading or title.

For more detailed guidance, see Headings and titles in the Google developer documentation style guide.

Lists

For guidance on writing lists, see Lists in the Google developer documentation style guide.

Objectivity and trust

While we write XMTP documentation to help people understand concepts and how to perform tasks, another goal is to build developer and user trust. A part of building this trust is writing objectively and credibly, without using marketing jargon and buzzwords.

From Google Cloud/Apigee's Developers Hate Marketing ebook, based on developer market research:

The first mistake many companies make with developers is to use the word marketing. Developers live in the world of the tangible. They want to see their apps used by people. They have a keen eye for anything that sounds like vaporware and have an immune response to traditional marketing approaches and offers.

We can also use Ethereum style guide's take on objectivity to inform how we write about XMTP. Here, we've borrowed their text and replaced Ethereum with XMTP:

XMTP documentation (and content at large) aims to maintain a credibly neutral source of truth to inform readers about XMTP and its ecosystem. Some examples of things that we don't want in the content on xmtp.org:

• Grand, unverifiable claims about XMTP or adjacent technologies
  e.g. "XMTP will take over the world because..."
• Hostile or confrontational language aimed at any organization or person
  e.g. "Company X is bad because they are centralized!"
• Politically charged rhetoric
  e.g. "This political party is better for decentralization because..."

Present tense

Write in the present tense whenever possible. Minimize the use of past tense or future tense in your writing.

To learn more, see Present tense in the Google developer documentation style guide.

In documentation in particular, avoid making forward-looking statements and using words like new and currently that anchor content to a specific point in time.

To learn more, see Timeless documentation in the Google developer documentation style guide.

Subjunctive mood

The subjunctive mood expresses doubt and causes confusion over whether you're making a recommendation or stating a requirement. Whenever possible, make it clear whether XMTP does or doesn't do or require something. For clarity, we avoid the following subjunctive mood verbs:

• could
• should
• would

Note that you can use these terms in contexts where they are explicitly defined, such as in specifications conforming to RFC-2119.

Correct	Incorrect
✅ For security reasons, give only administrators access to this instance. The example shows a type of script you can create for your deployment. Start by setting up a new stanza in the transforms.conf file.	⛔️ For security reasons, only administrators should have access to this instance. The example shows a type of script you would create for your deployment. You could start by setting up a new stanza in transforms.conf.

Qualitative language

Avoid qualitative language, such as referring to tasks as being easy, quick, fast, or simple. What's easy for one user might be challenging for another.

Voice and tone

Voice, like a personality, is pretty static. For example, we write xmtp.org content using a voice that aims to be:

• Approachable
• Credible
• Straightforward

Beyond our persistent voice, or personality, the tone we use to write on xmtp.org changes as an expression of personality based on context, or content types. For example, here is a spectrum showing the range of tones we use to write different types of content on xmtp.org:

Writing about how messages move using XMTP

Messages move in a variety of ways with XMTP. Here are some content patterns we can use to help describe these movements with accuracy, clarity, and consistency.

How messages move between client apps:

• A client app subscribes to a direct message topic
  • Different from retrieve
• A client app submits a message to the network
• A client app retrieves a message from the network
  • Don't use fetch
• A client app presents a message to a user
  • Don't use delivers

How messages move between XMTP nodes:

• A node relays a message to other nodes
• A node relays key bundles to other nodes
• Don't use publish

How messages move between human users:

• A user composes a message in a client app
• A user sends a message to another user
• A user receives a message from another user