Open Payments style guide

Before committing changes

1. Your PR title must contain the appropriate prefix (docs:).
2. Run the following command in the doc directory:

   npx prettier . --write

   You can also try the following. It might work, or you might get an error.

   pnpm format

After a Starlight upgrade to open-payments

cd <to project folder>
pnpm install
cd docs
pnpm start

Nouns

Common nouns

• payment pointer
• wallet address

Proper nouns

• Interledger
• Interledger Protocol (can abbreviate as ILP after the first use on a page)
• Open Payments (always spell out, don’t abbreviate as OP)
• Rafiki
• Web Monetization (always spell out, don’t abbreviate as WM)

Spellings

Open Payments

Spell as two words, not one (OpenPayments).

Concept docs

All concepts docs (and the getting started overview) should have a summary at the top that gives a TL;DR of the contents/purpose of the page.

For now, we’re using the :::tip aside with the default rocket icon. In newer versions of Starlight, you can use custom icons. We’ll replace the rocket when our version is updated.

https://starlight.astro.build/components/asides/#use-custom-icons

Developer guides

The following sections, at minimum, should be included in all Open Payments developer guides. Included below are some highish-level style standards, but you should look to existing guides for the bigger picture.

Summary

Use the :::tip aside and briefly describe the purpose of the guide. Don’t repeat the page title.

Overview

Include some general information about the guide that helps to set up the subsequent Scenario section.

For example, in Set up recurring payments with a fixed incoming amount, we use a “subscription payment” as a general example of a recurring transfer of money of the same amount. Then, the scenario section uses “streaming service” as a specific kind of recurring subscription.

Scenario

Describe the specific scenario the guide will cover. Include values for things like currency type, amount, recurrence schedule, etc. The guide’s steps must follow what you describe here.

List and define the parties involved in the scenario. One will always be the reader of the guide and the role they’re assuming (developer, platform operator, etc.). Other parties could include merchant/retailer, service provider, customer, sender, recipient.

Bold the party name and use a (bold) colon. Then include the description in normal text. For example:

• Retailer: the athletics company
• Developer: you, as the developer working on the client appropriate

Note

This was a style that naturally came about, not one that was discussed. If you find guides that don’t follow this format, update them. Not a high priority.

Remember to refer to existing guides for examples.

Endpoints

Provide a bulleted list of every API that’s used in the guide. Prefix each API with the appropriate Badge and wrap each API name in the LinkOut component.

<Badge text="GET" variant="note" />

<Badge text="POST" variant="success" />

<Badge text="DELETE" variant="danger" />

If the guide mentions optional APIs, exclude them from this list. This list is what’s required.

Steps

• The steps themselves
• Step overview
• Code for requests
• Code for responses

The steps themselves

• Each step number is a heading (usually an H3).
• Each step starts with a verb (no -ing suffix).
• Use existing guides as a template for how to word the steps. For example, Request the creation of an incoming payment resource is wordy, but it clearly indicates we’re talking about a resource, not a grant.

Step overview

• Each step should have some kind of explanation about its purpose.
• If you’re instructing someone to call an API, prefix the API name with the appropriate Badge component (see Endpoints) and relative-link the name of the API to its page. If you’re only mentioning an API, exclude a Badge or link.

Code for requests

Request snippets should come from a developer. If the developer is nice enough to add the snippets to the doc, review the markdown to make sure it’s formatted correctly.

• Each step should use a synced Tabs component (<Tabs syncKey="lang">).
• Each language should have its own tab and include the lang’s icon, if available.
• Each code block should specify the lang and use the wrap property (```ts wrap).

Update each snippet, when possible, to be specific to your scenario. Look at other guides for examples. You might need a developer to help with parts of it.

If you think a parameter or value needs additional explanation, use a double backslash and add a comment to the end of the line (// the management uri).

Note

Don’t add blank lines between code in a block. It causes errors.

Code for responses

We should be able to create the API responses by using the snippets and our API docs.

When formatting the response:

• Hide the response in a <detail> element.
• Use Example response (or similar) as the summary.
• Include a descriptive sentence or two about where the response is coming from.
• Use ```json wrap in the code block.

Note

Don’t add blank lines between code in a block. It causes errors.

When revising the response’s values:

• Make sure they’re specific to your scenario.
• Pay attention to timestamp values (e.g., createdAt). They should incrementally increase as the steps progress.
• Fully or partially abbreviate long values that aren’t needed to understand the flow. We commonly use this for access tokens, UUIDs, ilp addresses, and shared secrets. Add an inline comment to the end of the line describing what the value represents.
  • If abbreviating the whole value, use "...".

    Example

    {
      "access_token": {
        "value": "...", //access token value for incoming payment grant
      }
    }

  • If abbreviating part of a value, use {...}.

    Example

    {
      "manage": "https://auth.happylifebank.example.com/token/{...}", // management uri for access token
    }