Introducing the Moodle content style guide 🎉

Introducing the Moodle content style guide 🎉

by Zoe Rippon -
Number of replies: 6
Picture of Moodle HQ team

Hi Everyone, 

We're really excited to share with you the launch of Moodle’s first content style guide. 

This guide helps us create a clear and consistent approach to the content we produce across the Moodle ecosystem: from our websites, marketing and communications to the actual text across Moodle’s products. 

The guide is a living artefact and will grow and evolve over time. When the team at HQ makes any updates to the guide, they'll be reflected in real-time, making it easy for you to keep up-to-date.


What’s in the content style guide?

The guide includes our voice and tone, grammar and language mechanics; and a list of terms. While we have created the guide in English, we have a section about how we write for internationalisation. This section includes recommendations to help us all write in a way that makes it as easy as possible for our Translators to do their job. 


How should you use the guide?

It's a useful tool to refer to when building contributions to Moodle products, helping us all, over time, to create a consistent experience for everyone using Moodle.. 


What’s next on the roadmap

While the Content style guide is public and available to everyone, plans on our roadmap also include embedding UX writing in sources that the Moodle community and our teams at Moodle HQ use daily. Our long term goal is to make sure that any components with UX copy in the developer docs, user documentation, and the component library follow best practices and can easily be used as a reference for anyone contributing to Moodle.

Average of ratings: Useful (4)
In reply to Zoe Rippon

Re: Introducing the Moodle content style guide 🎉

by Richard Samson -
This is very impressive work. It's a great start. Congratulations to the UX team!
Average of ratings: -
In reply to Richard Samson

Re: Introducing the Moodle content style guide 🎉

by Zoe Rippon -
Picture of Moodle HQ team
Thanks for the feedback Richard! 😊 The team have done an incredible job!
Average of ratings: -
In reply to Zoe Rippon

Re: Introducing the Moodle content style guide 🎉

by Przemek Kaszubski -
Good to see this initiative !

Not sure my suggestion belongs here, or whether it should be addressed to the developers, but since I see concern expressed in your doc for translators' work, let me share my idea here.

I think content creators (and the HQ team too) should pay (more) attention to the phenomenon of homography in English - especially when language strings to be translated are devised. Economy of labelling can lead to ambiguity and error in translation.

Recently, the language string ID "grade" in the Moodle core has been - thankfully ! - replaced by two forms - "grade_noun" and "grade_verb" - which of course translate very differently in most languages. I very much welcome this change, and would like to see more of it in the various contexts of the Moodle code.

Many short words (word-strings) in English can be ambiguous in the same or similar way. One of my "favourite" examples is:
"view" - which may be a singular noun or a basic verb form (imperative, usually)
And so I believe it also calls for splitting into:
"view_noun" vs "view_verb"
if sensible translations of the word are to be produced (in translations of log menus, various report templates etc.)

Maybe a list of some recommended unambiguous usages of basic short English language strings could be compiled? They need not be verb-noun variations only, although I can't think now of examples of other grammatical distinctions affecting Moodle contents (e.g. noun-adjective, adjective-adverb or past vs passive verb pairs).

Perhaps you will find this observation and comment useful / applicable in some way.

Kind regards.
Average of ratings: Useful (2)
In reply to Przemek Kaszubski

Re: Introducing the Moodle content style guide 🎉

by Zoe Rippon -
Picture of Moodle HQ team
Thank you for the suggestion @Przemek it is a very valid point. I will make sure the team have a look at this and see where it might fit.
Average of ratings: -
In reply to Zoe Rippon

Re: Introducing the Moodle content style guide 🎉

by Helen Foster -
Picture of Moodle HQ team

Thanks Richard and Przemek for your feedback. smile

Przemek, if you come across more instances of English words which can be translated differently depending on the context, please make sure they are reported in the Moodle Tracker, as new language strings need to be added by a developer.

Many thanks to everyone for helping improve the words and phrases used in Moodle by contributing to the English fixes language pack (as described in our guide Improving English language strings). When we review your contributions, we'll be checking that they follow the content style guide, and adding to it.

Average of ratings: Useful (2)
In reply to Helen Foster

Re: Introducing the Moodle content style guide 🎉

by Przemek Kaszubski -
Thanks Zoe and Helen smile

I will be reporting any string issues to the Tracker.

Since the problem can indeed affect plugins (where separate strings may be devised outside of the core ones), I thought including (some) such cases as part of the Moodle policy (advice for developers?) could be helpful, if it is not yet being done.
In fact, that case with "view" was spotted by me in one of the plugins, as far as I recall, but I'd need to dig out my notes and screenshots to verify. I'll then try to report that as an improvement suggestion (tracker or github) to the developers of the plugin.

Kind regards.

Przemek
Average of ratings: -