-
Notifications
You must be signed in to change notification settings - Fork 3
Voice
Contrary to what some people seem to believe, simple writing is not the product of simple minds. A simple, unpretentious style has both grace and power. By not calling attention to itself, it allows the reader to focus on the message. —Richard Lederer and Richard Dowis, Sleeping Dogs Don’t Lay
The 'voice' of your curriculum codifies how you 'address' your students from written content. While you should keep your own 'unique' voice to add authenticity of your writing, a simple style will always be appropriate. Here are some guidelines on keeping a standard 'voice' throughout.
Our curricula needs to appeal to a very wide variety of age groups, from Middle School students up to faculty, career-changing professionals, and beyond. For this reason, we write simply and inclusively.
Use Alex.js to check for non-inclusive terms. There is a good Alex VS Code extension that acts as a linter and can check for problematic words and phrases.
Some articles about inclusive writing include:
- NAU's inclusive writing guide
- Writing Inclusive Copy by Crescendoworks
- Microsoft's Bias-free communication documentation
Much of the content you write might be translated by community people, so it's important to have very clear and concise English phrases that are easily translated. Avoid culturally-specific language, sports metaphors, sarcasm and jokes.
Make sure not to include
/en-us/in Learn/Docs links, so that the user will be redirected to content in their language automatically.
Make sure to give credit to any reused content, images, or ideas. A blockquote with a link can often suffice.
Spell-checking is good, and proofreading is better. Beware the improper use of it's/its, their/they're, and other grammatical mistakes.
Write as if you are addressing an audience as a friendly lecturer. Use terms such as 'In this lesson, you will learn' rather than 'In this lesson, we'll learn' or 'I will teach'. This style helps students feel included and as if the lesson was written with them in mind. Using phrases such as 'you will learn' imparts your confidence that they WILL be able to grasp the concepts. It is a self-fulfilling prophecy!
Light colloquialisms and contractions (you'll, we'll) are acceptable in moderation.
Write for beginners. If you find yourself needing to use specialized technical words or phrases, call them out and explain them as simply as possible. Use the active voice and action verbs for a lively flow.
Help students further their knowledge, but don't rewrite documentation. Use blockquote callouts with links to learn more, rather than writing in depth about a given topic that is better covered in documentation. Include instrumented links to Microsoft Learn modules for students. For specific jargon vocabulary that needs to be understood in a lesson, use emoji callouts to explain the jargon briefly, with a link to learn more.
Here is an example of a good writing style for our curricula:
In this series of lessons, you'll learn how to build a browser extension that will work on Chrome, Firefox and Edge browsers. In this part, you'll discover how browsers work and you'll scaffold out the elements of the browser extension.
But what is a browser exactly? It is a software application that allows an end user to access content from a server and display it on web pages.
✅ A little history: the first browser was called 'WorldWideWeb' and was created by Sir Timothy Berners-Lee in 1990.
In this example, the author addresses the audience directly and explains a term with an explanation and a callout.
Let's start by building the HTML for the form and styling it with CSS.
In the /dist folder, you will build a form and a result area. In the index.html file, populate the delineated form area:
In this example, there's an invitation to start together, as this lesson is interactive. The author invites the user to participate, tells what is expected, and then gives a series of imperative instructions for the user to perform.