Skip to content

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

Merged
rakekniven merged 5 commits into
masterfrom
feature/ux-writing-guide
May 21, 2026
Merged

docs(design): add UX writing guide for user-facing strings#14962
rakekniven merged 5 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 (never all uppercase)
  • Nextcloud naming rule: always Nextcloud — capital N, lowercase c; never NextCloud or Nc
  • Drop "successfully" anti-pattern (before/after table)
  • Specific error messages with actionable text
  • Tone (friendly, not chatty; no exclamation marks in status text)
  • Names, pronouns, and gender: full names, avoid my/your, gender-neutral language
  • 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: Thu, 21 May 2026 10:44:03 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 :)

nimishavijay
nimishavijay requested changes May 21, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@nimishavijay nimishavijay left a comment

Choose a reason for hiding this comment

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

Really really nice, covers a lot of bases! I will then remove the writing section from my design guidelines! Suggested some things to add so that we are not losing anything from the existing guidelines :)

Comment thread developer_manual/design/writing.rst
Comment thread developer_manual/design/writing.rst Outdated
Comment thread developer_manual/design/writing.rst
Comment thread developer_manual/design/writing.rst
@skjnldsv
docs(design): address review feedback on UX writing guide
20be492 
- Add Nextcloud naming rule (capital N, lowercase c, no NextCloud/Nc)
- Add "never all uppercase" to sentence case rule with SHARE example
- Add names, pronouns, and gender section (full names, avoid my/your,
  gender-neutral language with link to international guide)
- Move destructive actions note above the button labels table

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 21, 2026

Done @nimishavijay !!
20be492 (this PR)

@skjnldsv skjnldsv requested a review from nimishavijay May 21, 2026 08:22
@skjnldsv skjnldsv enabled auto-merge May 21, 2026 08:22
nimishavijay
nimishavijay approved these changes May 21, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@nimishavijay nimishavijay left a comment

Choose a reason for hiding this comment

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

Amazing! :D

@rakekniven rakekniven disabled auto-merge May 21, 2026 08:46
@rakekniven rakekniven enabled auto-merge May 21, 2026 08:46
jancborchardt
jancborchardt reviewed May 21, 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.

I will then remove the writing section from my design guidelines!

@nimishavijay probably best to cross-link though, so it's clear where it went. Also we need to keep it for the DESIGN.md

@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 21, 2026 •
edited
Loading

image

@rakekniven avoid doing rebases if there are no conflicts please, we already have a pretty high CI usage 🙏

@rakekniven
Copy link
Copy Markdown
Member

rakekniven commented May 21, 2026

@rakekniven avoid doing rebases if there are no conflicts please, we already have a pretty high CI usage 🙏

Sorry, I didn't mean to do that. I clicked too quickly in the web interface.

@skjnldsv
Copy link
Copy Markdown
Member Author

skjnldsv commented May 21, 2026

All good eheh 🤗

@skjnldsv skjnldsv self-assigned this May 21, 2026
@rakekniven rakekniven merged commit e15efeb into master May 21, 2026
28 checks passed
@rakekniven rakekniven deleted the feature/ux-writing-guide branch May 21, 2026 10:44
@github-project-automation github-project-automation Bot moved this from 🏗️ At engineering to 🎉 Done in 🖍 Design team May 21, 2026
This was referenced May 21, 2026
Merged
Merged
Merged
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

@nimishavijay nimishavijay nimishavijay approved these changes

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

@susnux susnux Awaiting requested review from susnux

Assignees

@skjnldsv skjnldsv

Labels

4. to release enhancement manual: developer

Projects

🖍 Design team
Status: 🎉 Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add section about how to formulate messages

4 participants

@skjnldsv @rakekniven @jancborchardt @nimishavijay