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

@skjnldsv skjnldsv commented May 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

☑️ 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

skjnldsv commented May 20, 2026

Copy link
Copy Markdown
Member Author

/backport to stable34

@skjnldsv

skjnldsv commented May 20, 2026

Copy link
Copy Markdown
Member Author

/backport to stable33

@skjnldsv

skjnldsv commented May 20, 2026

Copy link
Copy Markdown
Member Author

/backport to stable32

@github-actions

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

Copy link
Copy Markdown
Contributor

📖 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

skjnldsv commented May 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

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

@jancborchardt jancborchardt left a comment

Copy link
Copy Markdown
Member

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

skjnldsv commented May 20, 2026

Copy link
Copy Markdown
Member Author

Will wait for Nimisha's input

@skjnldsv

skjnldsv commented May 20, 2026

Copy link
Copy Markdown
Member Author

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

@nimishavijay nimishavijay left a comment

Copy link
Copy Markdown
Member

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

skjnldsv commented May 21, 2026

Copy link
Copy Markdown
Member Author

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

@nimishavijay nimishavijay left a comment

Copy link
Copy Markdown
Member

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

@jancborchardt jancborchardt left a comment

Copy link
Copy Markdown
Member

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

skjnldsv commented May 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author
image

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

@rakekniven

rakekniven commented May 21, 2026

Copy link
Copy Markdown
Member

@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

skjnldsv commented May 21, 2026

Copy link
Copy Markdown
Member Author

All good eheh 🤗

@skjnldsv skjnldsv self-assigned this May 21, 2026
@rakekniven
rakekniven merged commit e15efeb into master May 21, 2026
26 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
Archived in project

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