Wikifunctions:Design/Naming conventions recommendations
Context
As we get closer to integrating Wikifunctions with Wikipedia, the Abstract Wikipedia team wants to share a few suggestions to ensure that Wikifunctions content is accessible, inclusive, and cohesive across projects.
Possible scenario
While testing how functions might look and feel on Wikipedia, we noticed that the user interface text (also known as names, messages, or titles) was following different standards. For instance, we observed that text in the Wikipedia user interface—in yellow—is usually more concise and, in languages that support casing, uses sentence case (where only the first letter of the first word is uppercase), while text in the Wikifunctions user interface—in green—is more descriptive, and is usually set in full lowercase.
Disclaimer
The Abstract Wikipedia team is aware of the draft published under Wikifunctions:Naming conventions, and would like to offer some support in potential proceedings of said draft. The following recommendations focus only on Wikifunctions content that will be exposed to Wikipedia, and that includes:
- Function definitions: name, description, and input labels
- Placeholder texts: usually the result of a test of a reading function
- Error messages: “built-in” (eg. Z5XX), or reading or display function implementation errors
Examples of where Wikifunctions content would be displayed on Wikipedia
| Insert function | Edit function | Preview function |
|---|---|---|
|
1 Function name |
1 Function name |
1 Function name |
|
|
|
Intro
These recommendations for writing text displayed inside a user interface are based on the overarching Wikimedia Design Principles (in bold) and the Codex voice and tone, and writing for copy guidelines. For each principle we drafted a question to consider when writing text:
- Content first → Is this content needed and relevant?
- Design for consistency → Is this content clear, concise and consistent?
- This is for everyone → Is this accessible, inclusive and translatable?
- Trustworthy yet joyful → Is this content trustworthy?
- Open to collaboration → N/A
Recommendations
Along with the specific recommendations, we also explored how each could be applied to existing text. The examples provided are illustrative only, and are not intended as suggestions for implementation. Instead, they are meant to help better understand how a specific recommendation could be applied to existing content. The Wikifunctions community is encouraged to use or adapt these suggestions as they see fit.
Content first
Is this needed?
Use single, descriptive words whenever possible. Given that Wikifunctions content will be mostly used as text to describe input fields on Wikipedia (like labels displayed above a text field or a selector), avoid using verbs unless necessary. Text is usually displayed inside a user interface, which already tells users to act upon, or enter information to continue.
| Current (get day of week from date (Z13163)) | Recommendation |
|---|---|
|
|
|
|
Is this relevant?
Explain only the specific purpose of a concept. Avoid references to other content that users might not be familiar with.
| Current (is a palindrome (Z10096)) | Recommendation |
|---|---|
| test if a string is the same when read forward and backward (see Z10553 for one with Unicode grapheme support) | Tests if a string is the same when read forward and backward. |
|
|
Design for consistency
Is this clear?
Clearly communicate the concept as it eases user understanding, and gives users confidence that they can make the right choice in order to achieve their goal.
| Current (second element (Z16360)) | Recommendation |
|---|---|
| Item 2 | Second item |
|
|
Is this concise?
Keep the text as short as possible so that it will fit on small screens or narrow user interface selectors.
| Current (Arabic to Roman numeral (Z11022)) | Recommendation |
|---|---|
| Arabic to Roman numeral | Roman |
|
|
Is this consistent?
Use consistent language and sentence patterns when describing concepts across all content.
| Current (previous day of the week (Z17435), count a day of the week in a year (Z17536), days from one day to another (Z17578)) | Recommendation |
|---|---|
|
|
|
|
This is for everyone
Is this accessible?
Write for everyone, no matter their background, language, culture, ability, or identity. Avoid abbreviations, as they can be difficult to understand and hard to read for screen readers.
| Current (get nth date of a given day in month (Z17549)) | Recommendation |
|---|---|
| get nth date of a given day in month | Date from occurrence |
|
|
Is this inclusive?
Use simple language. Avoid technical jargon unless necessary.
| Current (ROT25 (Latin alphabet) (Z10851)) | Recommendation |
|---|---|
| ROT25 (Latin alphabet) | Letter shift |
|
|
Is this translatable?
Use easy-to-understand words and simple phrases. Avoid idioms, slang, metaphors, or other culturally specific references.
| Current (pretty " (Z11484)) | Recommendation |
|---|---|
| pretty " | Curly quotes |
|
|
Trustworthy yet joyful
Is this trustworthy?
When the content is reliable users can achieve their goals with confidence. Consistent overall messaging that is clear and effective also builds trust with a user.
Feedback
How do you feel about the current recommendations? What are the suggestions that could work, and what could be improved upon? Let us know in the discussion page.