Writing for Upscore Docs

This page is for whoever writes the docs. It is not linked from the sidebar.

Names

• Upscore is the app. Edi (エディ) is the coach you talk to inside it. Never write “the Edi app”, “download Edi”, or “Edi is available on iOS”. Ask of every sentence: is this the app, or is this who you talk to?
• Write Upscore, not “the app”, once per page at least. “The app” is fine after that.
• Upscore Pro and Upscore League are the subscriptions. Capitalised, no “the”.
• “Songs” means attempts. If you mean distinct charts, say charts.
• LIFE4 is uppercase. e-amusement is lowercase with a hyphen. Sanbai is Sanbai.

Voice

• Friendly, short, direct. One idea per sentence.
• No em dashes. Use a full stop, a comma, or parentheses.
• No “simply”, “just”, “easily”. If it were easy there would be no page.
• Soften claims you have not verified. “Usually”, “most watches”, “in our testing”.
• Talk to the reader as you. Talk about Upscore as Upscore or it, never we in instructions.

Structure

Every page has one H1 (the title from frontmatter), and starts with one or two sentences saying what the page is for. Then headings. Never skip a level.

Three page shapes

Copy one of these. Do not invent a fourth.

How-to

---
title: Connect an Apple Watch
description: Turn on heart rate for Session Mode on iPhone.
platform: ios
---

One sentence on what you will have at the end.

## Before you start

- What you need.

## Steps

<Steps>

1. First thing you tap.

2. Second thing you tap. What you should see.

</Steps>

## If it didn't work

Link to the matching troubleshooting page.

Reference

---
title: What syncs from e-amusement
description: Every field Upscore reads from e-amusement and how often.
---

What this is and who it is for.

## Fields

| Field | Where it shows | Notes |
|---|---|---|

## Limits

Troubleshooting

Each H2 is a literal question the reader is asking themselves. Keep the answer under the heading short and end with what to do next.

## My heart rate is flat at zero during songs

Why it happens. What to check, in order. When to contact us.

Components

Use these instead of hand-rolled markdown. They are available on every page with no import.

• <Steps> around any numbered procedure.
• <Aside type="note|tip|caution|danger" title="..."> for callouts. One per section at most.
• <Tabs syncKey="platform"> + <TabItem label="iPhone"> / <TabItem label="Android"> whenever the platforms differ. The sync key means a reader who picks Android once sees Android everywhere.
• <Badge text="Pro" variant="tip" /> inline next to a feature that needs Pro or League.
• <LinkCard> / <CardGrid> on section overview pages.

See the component gallery for every one rendered.

Images

Screenshots go in public/images/ and are referenced as /images/name.png. Name them feature-screen-platform.png, for example session-start-ios.png. Export at 2x, crop to the relevant part of the screen, and prefer WebP if the file is over 300 KB.

Japanese

Every page can have a Japanese twin at the same path under ja/. Until it exists, Japanese readers see the English page with a notice. Terminology follows the termbase in the app repo (足14, 譜面, 捻り, 縦連, 踏む). Do not guess a term that is not in it.