Writing Style Guide

This guide defines the writing conventions for this migration so contributions from many teams still read like one documentation set.

For component usage and supported shortcodes, see:

• src/labs/content/shortcode-gallery.md
• src/labs/content/content-style-guide.md (visual/audit sandbox)

Goals

• Make pages scannable and task-oriented.
• Keep wording precise and technically reliable.
• Reduce translation friction (EN/JA) by using clear structure and simple phrasing.
• Keep authoring consistent so we can migrate at scale without rewriting everything later.

Voice and tone

• Prefer direct, calm language. Avoid hype and vague marketing claims.
• Use imperative for procedures: "Select", "Create", "Verify".
• Prefer "you" only when it clarifies who performs an action (avoid conversational filler).
• Use consistent product naming (don't invent synonyms).

Page structure

Use predictable sections so readers can find what they need:

• Start with a 1-2 sentence summary that states the outcome.
• Add prerequisites before steps.
• Use headings that reflect tasks or decisions, not internal terminology.

Good heading examples:

• "Create a SIM group"
• "Configure virtual private gateway"
• "Troubleshoot connection errors"

Avoid:

• "Overview" repeated on many pages without meaning.
• Headings that are just product names with no intent.

Procedures and steps

• One step = one user action.
• Put the verb first. Keep steps short.
• If a step has conditions, split into a decision point ("If..., then...").
• Prefer numbered steps for procedures; use unordered lists for collections.

Terminology and UI labels

• Wrap UI labels and tokens in inline code: SIM Group, Status, Operator API.
• Use the exact label seen in the UI (case-sensitive) when possible.
• Define acronyms on first use (unless they're universally known in Soracom context).

Links

• Link text should describe the destination, not "click here".
• Prefer stable internal links and keep anchors meaningful.
• When linking out, use the official canonical page where possible.

Code and commands

• Use fenced code blocks for commands and snippets.
• Prefer bash / json / yaml info strings for syntax highlighting.
• Don't embed explanatory prose inside code blocks.
• If a sample has output, use the code example helper so copy only captures the sample (see shortcode gallery).

Callouts and emphasis

• Use callouts for content that would otherwise be missed or misapplied:
  • limits, irreversible actions, billing impact, security warnings
• Use emphasis sparingly. Avoid underline and decorative styling.
• Prefer semantic callout types where supported so visuals stay consistent.

Tables

• Use Markdown tables for simple comparisons.
• Use an advanced table helper only when you need sticky headers/columns or complex layout.

Accessibility and inclusive writing

• Avoid "simply", "just", or blame language ("obviously", "easy").
• Describe UI interactions without relying on color alone.
• Prefer descriptive alt text for informative images; omit redundant alt text for purely decorative images.

Localization considerations (EN/JA)

• Keep sentences short and avoid idioms.
• Keep lists and headings structurally parallel across locales.
• Locale-specific entry pages are allowed when they reduce friction, but the IA and component patterns should remain consistent.

"Final" vs "needs refinement"

When adding or editing content, be explicit about whether what you're writing is:

• Final content (meant to be migrated as-is), or
• Scaffolding (placeholder pending decisions, design, or product changes)

If something is scaffolding, say so in the PR description and link to the decision/open-question in PROJECT_STATUS.md.