​

Release Notes Style Guide

​

Voice & Tone

​

Voice Characteristics

​

Tone Guidelines

• Use contractions (“you’ll”, “can’t”, “don’t”)
• Address the reader as “you”
• Lead with benefits
• Be specific and concrete

• Use “we” or “our” (company-focused)
• Hedge with “hopefully”, “should”, “might”
• Use passive voice
• Include internal jokes or references

​

Verb Tense

​

Present Tense (Active)

• ✅ “Adds playlist collaboration”
• ✅ “Improves dashboard loading speed”
• ✅ “Introduces new upload flow”

​

Past Tense

• ✅ “Fixed login timeout error”
• ✅ “Resolved mobile player crash”
• ✅ “Corrected billing calculation”

​

Present Perfect (Sparingly)

• ✅ “Has streamlined the approval process”
• ⚠️ Use sparingly—prefer simple present or past

​

Sentence Structure

​

Length

• Keep sentences under 25 words
• Break long sentences into bullets
• One idea per sentence

​

Examples

​

Bullet Points

• Lead with outcome/benefit
• Keep to one line when possible
• Use parallel structure

• Upload speed is faster
• We’ve improved the player
• Bug with login is fixed

• Faster uploads — Process tracks 50% quicker
• Improved player — Smoother playback on mobile
• Fixed login bug — No more timeout errors

​

Word Choice

​

Preferred Terms

​

Numbers

• Write 1-9 as words: “three new features”
• Write 10+ as numerals: “12% faster”
• Always use numerals for percentages, prices, dates
• Use “95%” not “ninety-five percent”

​

Time References

• “now” for immediate availability
• “today” for day of release
• “this week” for rolling releases
• Avoid “soon”, “eventually”, “coming soon”

​

UI References

​

Formatting

• Button text — **Save Changes**
• Menu items — **Billing**
• Page names — **Producer Dashboard**
• Section headers — **Current Plan**
• Navigation paths — **profile avatar** → **Billing**

​

Navigation Patterns

​

Examples

​

Tooltips

​

Purpose

​

Writing Tooltip Text

• One to two sentences maximum
• Define the term in the BeatPass context, not a generic dictionary definition
• Write in plain English — no code, no internal terminology
• Don’t repeat the term itself inside the tip

tip="Credits that control how many beat requests you can create each month. Your plan determines your allowance."

tip="A type of credit."

tip="Tokens are a credit system used by BeatPass to regulate the number of beat requests that users can create in a given calendar month. Each plan tier comes with a different monthly allocation of tokens which reset on the last day of the month and do not carry over."

​

When to Add a Tooltip

• It’s BeatPass-specific jargon (contribution value, tokens, platform fee, duration tier)
• It’s a technical term the audience may not know (Bearer token, webhook, rate limit, 2FA)
• It has a BeatPass-specific meaning different from everyday usage (exclusive license, Stripe Express)

• The term is common English (subscription, upload, download, payment)
• A <Note>, <Info>, or <Warning> already explains it in the same section
• The term has already been tooltipped earlier on the same page

​

Placement Rules

• First occurrence only — One tooltip per term per page
• Body text preferred — Place in running prose, not inside ## headings (exception: glossary-style headings where the heading IS the defined term)
• Works with formatting — Can nest inside bold: **<Tooltip tip="...">term</Tooltip>**
• Don’t use inside code blocks — Tooltips are for prose, not code examples

​

Cross-Linking with cta + href

<Tooltip tip="A score based on recency and plays that determines your revenue share." cta="See the formula" href="/help/earnings/contribution-system/formula">contribution value</Tooltip>

​

Prohibited Content

​

Never Include

1. Internal terminology
   • ❌ “music.create permission”
   • ✅ “ability to upload tracks”
2. Code or technical details
   • ❌ “Fixed null pointer in TrackController”
   • ✅ “Fixed crash when saving tracks”
3. Database/technical terms
   • ❌ “Added migration for user_settings”
   • ✅ “New settings available in your profile”
4. Internal IDs or slugs
   • ❌ “Updated notif_id: beat_request_match”
   • ✅ “Updated beat request notifications”
5. API endpoints
   • ❌ “POST /api/v2/tracks now supports…”
   • ✅ “Track uploads now support…”
6. Git references
   • ❌ “PR #1234 merged”
   • ✅ “New feature released”
7. Emoji
   • ❌ ”🎉 New feature! 🚀”
   • ✅ Use Mintlify icons only

​

Section Standards

​

Summary (2-3 sentences)

[What changed] for [who it helps]. This [benefit] by [how it works].

​

What’s New (3-7 bullets)

- **Benefit statement** — Specific capability or improvement

- **Collaborative editing** — Invite others to edit playlists with you
- **Permission levels** — Control who can add, remove, or view
- **Activity tracking** — See who made changes and when

​

Why It Matters (2-4 bullets)

- Save time on project coordination
- Share curation with your team
- Build community around your taste

​

How to Use (Numbered steps)

1. Navigate to **Page Name**
2. Click **Button Name**
3. Select **Option**
4. Verify [outcome]

​

Formatting Rules

​

Headers

• Use title case (“What’s New”, not “What’s new”)
• H2 for main sections
• H3 for subsections only if needed

​

Links

• Use descriptive text, not “click here”
• Root-relative paths: /help/page-name
• Test all links before publishing

​

Lists

• Use bullet points for unordered items
• Use numbered lists for sequential steps
• Keep list items parallel in structure

​

Tables

• Use for comparisons (before/after, options)
• Include header row
• Keep cell content brief

​

Length Guidelines

​

Examples: Good vs Bad

​

Title

​

Summary

​

What’s New

- Playlist collaboration feature
- Multiple users can edit
- Permissions system added
- Activity log included

- **Real-time collaboration** — Multiple users can edit simultaneously
- **Permission controls** — Set editor or viewer access per person
- **Activity tracking** — See who made changes with timestamps

​

Why It Matters

- Coordinate projects with your team
- Share curation duties with co-producers
- Build collaborative playlists for events

​

Quick Reference Card