Skip to content

docs(design): add UX writing guide for user-facing strings#14962

Open
skjnldsv wants to merge 3 commits into
masterfrom
feature/ux-writing-guide
Open

docs(design): add UX writing guide for user-facing strings#14962
skjnldsv wants to merge 3 commits into
masterfrom
feature/ux-writing-guide

Conversation

@skjnldsv
Copy link
Copy Markdown
Member

@skjnldsv skjnldsv commented May 20, 2026 •
edited
Loading

☑️ Resolves

Summary

Adds developer_manual/design/writing.rst — a practical guide for developers on how to write user-facing strings (notifications, errors, button labels, etc.).

Covers:

  • Keep messages short, sentence case
  • Drop "successfully" anti-pattern (before/after table)
  • Specific error messages with actionable text
  • Tone (friendly, not chatty; no exclamation marks in status text)
  • Button labels: verb + noun, specific verbs for destructive actions
  • Variable/placeholder gotcha — no split strings across concatenation (breaks translation)
  • Cross-ref to translations.rst for implementation details

Added to design/index.rst toctree after introduction.

🖼️ Screenshots

✅ Checklist

  • I have built the documentation locally and reviewed the output
  • Screenshots are included for visual changes
  • I have not moved or renamed pages (or added a redirect if I did)
  • I have run codespell or similar and addressed any spelling issues

@skjnldsv
docs(design): add UX writing guide for user-facing strings
ba73a67 
Adds a new writing.rst page to developer_manual/design/ covering tone,
message brevity, the "successfully" anti-pattern, button label conventions,
and variable/placeholder gotchas for translators.

Linked from design/index.rst toctree.

Relates to #13884

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 20, 2026

/backport to stable34

@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 20, 2026

/backport to stable33

@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 20, 2026

/backport to stable32

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 20, 2026 •
edited
Loading

📖 Documentation Preview

🔍 Open preview →

📄 3 changed documentation pages

Last updated: Wed, 20 May 2026 08:32:57 GMT

@skjnldsv
docs(design): add translator comments section to UX writing guide
4573c24 
Explains when and how to write TRANSLATORS comments in PHP, JS/TS,
Vue templates, and Vue script blocks, with examples from the server codebase.

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
@skjnldsv skjnldsv requested a review from susnux May 20, 2026 08:07
@skjnldsv
docs(design): split translator hints between writing guide and transl…
e1dfad2 
…ations ref

Move code examples for TRANSLATORS comments to basics/translations.rst
(the implementation reference) and keep only prose guidelines in
design/writing.rst. Cross-link both directions so neither page duplicates
the other.

- writing.rst: strip code blocks from Translator comments and Placeholders
  sections; add cross-refs to translations.rst
- translations.rst: improve PHP/JS/Vue TRANSLATORS examples (Vue template
  uses <!-- --> above element, add multi-line PHP pattern); add ref label
  improving-translations for cross-linking

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 20, 2026 •
edited
Loading

A bit of duplicates infos, adjusting ⏳

EDIT: done 👍

@jancborchardt jancborchardt moved this to 🏗️ At engineering in 🖍 Design team May 20, 2026
jancborchardt
jancborchardt reviewed May 20, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@jancborchardt jancborchardt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good!

I would only add that we should prevent excessive notification sending for successful actions which are obviously communicated in the interface (e.g. "Added as favorite") – but that's not a blocker, and might be better placed in the design guidelines.

Also @nimishavijay for review as she is updating the design guidelines at the moment.

@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 20, 2026

Will wait for Nimisha's input

@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 20, 2026

I would only add that we should prevent excessive notification sending for successful actions which are obviously communicated in the interface (e.g. "Added as favorite") – but that's not a blocker, and might be better placed in the design guidelines.

that looks less like a writing issue, but more like a UX problem that needs another section somewhere :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jancborchardt jancborchardt jancborchardt approved these changes

@rakekniven rakekniven rakekniven approved these changes

@kra-mo kra-mo Awaiting requested review from kra-mo

@susnux susnux Awaiting requested review from susnux

@nimishavijay nimishavijay Awaiting requested review from nimishavijay

Assignees

No one assigned

Labels

3. to review backport-request enhancement manual: developer

Projects

🖍 Design team
Status: 🏗️ At engineering

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add section about how to formulate messages

3 participants

@skjnldsv @jancborchardt @rakekniven