EdX Style Guide - Read the Docs...EdX Style Guide, Release CHAPTER 2 Preferred Usage can, might, and...

EdX Style GuideRelease

Jan 30, 2018

Contents

1 Introduction 1

2 Preferred Usage 3

3 Word List 5

4 Documenting User Interface Interactions 7

5 Topic Templates 9

6 Style Conventions and Content Layout 13

7 Images 15

8 Guidelines for Writing Global English 25

9 Media Accessibility 31

10 Working with edX Documentation Source Files 37

11 Guidelines for Translators 43

12 Documentation Translation Process 47

13 Example .rst File 49

14 Glossary 63

i

ii

CHAPTER 1

Introduction

The purpose of this guide is to provide a reference for documentation standards used in edX technical publications.Its intended audiences are members of the edX documentation team, other edX employees, and translation teams andopen source contributors around the world.

The edX documentation team follows the Microsoft Manual of Style, 4th edition. This guide documents terms andusage choices that are not covered by the Microsoft Manual of Style. It also documents company and team decisionsabout usage that differ from the Microsoft Manual of Style.

1

EdX Style Guide, Release

2 Chapter 1. Introduction

3


CHAPTER 2

Preferred Usage

can, might, and may Use the verb “can” to describe ability, capability, or capacity. Use “might” to describepossibility or eventuality. Because “may” implies permission, the edX documentation teamprefers to use one of the other two verbs.

capitalization Use title capitalization for headings. When referring to elements in the user interface, followthe capitalization that is used in the labels or text.Do not capitalize job titles, such as professor, instructor, or program manager. Do notcapitalize terms unless they are trademarks, so refer to the instructor dashboard or a courseabout video rather than the Instructor Dashboard or a course About video.

contractions Do not use.cross-references Introduce standalone cross-references to other edX topics with the phrase, “For more infor-

mation, see :ref:`topic name`”. To include more specific information about thematerial you are referencing, use the expanded phrase, “For more information about taskor concept, see :ref:`topic name`”.Exception: In the glossary, cross-references to other glossary entries begin with, “See:ref:`topic name`” if the current entry consists only of the cross reference. Torefer to a related entry, use “See also :ref:`topic name`”.To include a cross-reference inline, extend the cross-reference to include a phrase thatmakes sense in context. In this example, to create a sentence with the correct capitalization,“course launch checklist” is added to the cross-reference markup. “To verify that the courseis ready for release, you can use the :ref:`course launch checklist<CourseLaunch Checklist>`.”For a cross-reference to an external resource, provide the title of the destination, not just aURL. This style promotes a better experience for those using screen readers. In addition,avoid repeating links to the same destination multiple times on a single HTML page.Exception: use “edx.org” to refer to the https://www.edx.org website.

dates Format dates as DD Mon YYYY or DD Month YYYY. For example, 11 Jan 2015. Donot use both date formats within the same .rst file.

first person Do not use “I” or “me” unless you are following the text of a user interface label or message.Avoid using “we”. If edX or another entity has established a best practice, identify the theentity that recommends that practice by name.

heading style Use title case for all headings. For a top level section heading and for topics that introduceconcepts, use a verb in gerund form to start the title. For topics that describe a procedure,use an imperative verb to start the title.For example, “Adding Course Updates and Handouts”, “Adding a Course Update”, and“Identify a Course Handout”.Avoid the use of nouns or noun phrases without a verb as headings.

hyphenation Minimize the use of hyphenated compounds. Present compound words as either two sepa-rate words or a single word. Use hyphens only when the meaning is unclear without them.For exceptions to this rule, see the word list.

images Minimize the use of screen shots. For more information, see Images.lists Introduce a list with a complete sentence that ends in a period. Do not use “the following”

as a noun or to introduce a list. Instead, include the noun. For example, “The .csv fileincludes the following columns.” or “When pretty printed, this comment has the followingformat.”“

pronouns Avoid ambiguous pronouns such as all, each, many, several, some, that, them, these, those.punctuation Avoid slashes, particularly “and/or”. They introduce ambiguity.

Avoid em dashes. Putting non-restrictive relative clauses into separate sentences leads tosimpler, clearer writing.Do not use smart quotes or smart apostrophes. Use the straight versions of these marks.

redundancy Avoid including unnecessary words. For example, instead of “Create a new noun”, use“Create a noun”, and instead of “Delete or edit an existing noun”, use “Delete or edita noun.”

steps To introduce an ordered list of procedural steps, use “To verb task, follow these steps.”Note the complete sentence and terminal period. For example, “To add a course update,follow these steps.”“

tables When you include a table, be sure to include a heading row. In addition, consider whethera stub column is appropriate. The heading row and stub column provide useful context forusers of screen readers.

word choice See the Word List for our preferred terminology. Avoid jargon, colloquialisms, and humor.Do not use non-technical words that are not in common use, such as “and so forth”, albeit,heretofore, thus, or whilst.Be careful of commonly used phrases that introduce ambiguity. For example, instead of“When the process completes. . . ” use “After the process completes. . . ”

4 Chapter 2. Preferred Usage

https://www.edx.org

5


CHAPTER 3

Word List

Term Description and Examplescourse team, courseteam member

Use instead of instructor, professor, course author, course staff, faculty, and so on.

discussion, coursediscussions

Use instead of forum or discussion forum.

drop-down, drop-down

The edX problem type is labeled “dropdown”. If it is necessary to describe a particular typeof user interface control, use drop-down.

The E-Commerceservice

The part of the edX platform that handles payments. Always use with “service”.

edx, edX, EdX The company name is presented in mixed case: edX or edX, Inc. However, when a sen-tence begins with the company name, the first letter is also capitalized, as in the followingexample. “EdX provides the edX Demo course. . . ” Present the edx.org website in all lowercase.

The edX mobile app There is one app, available for different platforms. Do not refer to edX mobile apps (plural).Refer to numbered versions for the different mobile platforms. For example, “Version 2.6.2of the edX mobile app for iOS is now available.” “The edX mobile app for Android nowsupports. . . ”

email Do not hyphenate e-mail, and use Email only at the start of a sentence or when using titlecapitalization. Use email to modify a noun. For example, prefer “Send an email message”to “Send an email”. Do not use as a verb.

GitHub The “H” is always capitalized.ID Capitalize. Use instead of “id” or “Id”.instructor dashboard Lowercase both words.learner Use instead of “student”, except when referring to a UI label.page Use instead of “tab” to refer to the different areas of the LMS that deliver content to learners.

In Studio, course teams can rename default pages and add pages. In the LMS, learners selectname of page and work with the content on that page.

partner manager Use to refer to partners’ main edX contact, not program manager. Do not capitalize eitherword.

plug-in Use instead of plugin or plug in.privilege Use instead of “user rights”. The roles that grant privileges to users are “course creator”,

“admin”, and “staff”. These role names should only be used when having the privilege isan explicit requirement to complete an activity.

sample Use instead of “snippet”. “Example” can also be used.section In the edX guides, use “section” to refer to any part of a guide that is a parent to other

content, including other sections or individual topics. Use instead of “chapter”.select Use instead of “click” (mouse), “press” (keyboard), or “tap” (smartphone). Accessible

alternatives are “choose” (for a UI element that becomes highlighted and remains on screen)or “activate” (for a UI element that causes the dialog box to close or the page to refresh).

sign in to (v) Use instead of “sign into”.sign-in (adj) Use instead of “login” or “log in”.smartphone One word. Use instead of “mobile device”. For example, Android smartphones and

iPhones.student dashboard Present both words in lowercase.third party (n),third-party (adj)

“Third party” is a noun: “This product comes from a third party”. “Third-party” is theadjective form: “third-party software”.

topic In the edX guides, the concepts or procedures that are the lowest level contents of a sectionare referred to as topics.

username Use instead of “user name”.XBlock Use instead of “Xblock” or “xBlock”.

6 Chapter 3. Word List

CHAPTER 4

Documenting User Interface Interactions

When you describe interactions with the user interface, refer to the control labels and do not describe the control types.

• Incorrect: In the Randomization drop-down list, click the Never option.

• Correct: From the Randomization list, select Never.

This convention reduces word count and makes the documentation less likely to go out of date after a software change.

Because screen readers organize all link selections together, and all button selections together, and so on, if you doinclude the control type, it is critical that you describe it as it is coded, even if it is styled to look like a different typeof control.

4.1 List of edX UI Elements

The edX documentation team makes an effort to use the aria-label values that identify elements of the user interfacein the document object model (DOM). This table lists edX-specific terms and exceptions to Microsoft style.

7


checkbox Use a single word, not “check box”. Users can select more than one checkbox at a time.Users “select” or “clear” a checkbox. They do not “check” or “deselect” them.

component editor Present in lower case.course accordion Do not use. Previously used to describe the course navigation pane.course navigationpane

On the Course page, the navigation frame for selecting sections and subsections. Use“course outline”.

course ribbon Do not use. Previously used to describe the unit navigation bar.dialog box Do not use “dialog” alone to refer to the user interface control. Do not use “modal” or

“modal dialog”.discussion naviga-tion pane

On the Discussion page, the navigation frame for selecting and filtering discussion cate-gories, subcategories, and posts.

field A control that accepts user input that is typed or pasted in. Use in place of “text box”.filmstrip Do not use.handout navigationsidebar

On the Course page, the navigation frame where learners can find links to course tools(such as bookmarks) and course handouts. Use “sidebar”.

icon A user interface control that has an image for a label instead of text. To identify icons, usethe mouseover help text as the icon label. If the icon does not have help text, such as anicon in a mobile app, it must be described.

learning sequence Do not use. Previously used to describe the unit navigation bar.left pane Do not use. On the Courses page, the navigation frame for selecting sections and sub-

sections is called the “course outline”. On the Discussion page, the navigation frame forselecting categories and subcategories is called the “discussion navigation pane”.

unit navigation bar The navigation frame that runs across the top of course pages in the LMS, with icons foreach unit in the selected subsection, and with Previous and Next options on either end.

4.2 Standards for User Interface Labels

When the edX documentation team writes or copy edits labels, we follow these standards.

Use title capitalization for labels for the following user interface elements.

• Page titles

• Tab titles

• Buttons (these usually have only a few words)

Use sentence capitalization for all other labels.

8 Chapter 4. Documenting User Interface Interactions

CHAPTER 5

Topic Templates

5.1 Writing Concept Topics

Concept topics answer “Why?” and What is. . . ?” questions. Concept topics build on existing audience knowledge toprovide general explanations, background information, and examples to help the reader understand a feature or task.

Concept topics explain abstract ideas and introduce terminology. Concept topics tend to be relatively unaffected byfeature enhancements over time: while additions might be needed to support new options and their use cases, theytend to require less rewriting than task topics.

Concept topics are typically followed by at least one task topic. When they introduce complex features, they can befollowed by a set of additional concept topics and related task topics.

5.1.1 Structuring a Concept Topic

At a minimum, a concept topic includes the following components.

• A title, phrased as a gerund.

• One or more body paragraphs.

It can also include the following additional structured information.

• One or more examples.

• Two or more subsections, marked by subheadings.

• A list of related topics.

For more information, see Using this Concept Template or its source concept_template.rst file.

5.1.2 Example Concept Topics

The Building and Running an edX Course guide contains these examples of concept topics.

9


• Using Cohorts in Your Courses introduces a complex topic. It includes several subsections to divide the conceptinto different facets. A list of related tasks is included at the beginning to redirect readers who might not needthis background information.

• Develop a Positive Discussion Culture uses examples to define the concept of a positive discussion culture,and then offers a concrete example of actions to take for each one. This topic also provides a link to a relatedtemplate.

• Using the Course Wiki introduces a section of related concepts and tasks. It defines a wiki in the context of anedX course, and provides example uses.

5.2 Using this Concept Template

You can duplicate and use the source concept_template.rst file to provide a starting point for your ownconcept topics.

Replace or remove this sentence, and all subsequent values within and including braces (), with your own text.

Place the introductory statement here.

Include a contents directive. This directive resolves to a set of linked cross references to the next level headings inthis file.

• Optional Overview

• Optional Procedure

5.2.1 Optional Overview

Description.

5.2.2 Optional Procedure

Before you begin this task, complete this list of prerequisites.

To provide the context for completing the task, follow these steps.

1. First step.

For more information about task topics, see Writing Task Topics.

5.3 Writing Task Topics

Task topics answer “How do I?” questions. They use a well-defined structure that describes how to accomplish aspecific goal by completing a procedure. A task topic contains a single procedure, which is made up of a series ofsteps. Each step describes a single action or command for the user to take. A step can also describe the step results.

One or more task topics typically follow each concept topic.

10 Chapter 5. Topic Templates

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohorts_overview.html#cohorts-overview

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/manage_discussions/moderate_discussions.html#develop-a-positive-discussion-culture

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_assets/course_wiki.html#course-wiki


5.3.1 Structuring a Task Topic

At a minimum, a task topic includes the following components.

• A title. The preferred phrasing is an imperative verb acting on a single noun. Examples include “Add a CourseTeam Member”, “Create an Email Message”, and “Place an Order”.

• Context. This paragraph is the value proposition for the topic. It presents information about why the user wouldcomplete this task in terms of a business or personal goal, and not in terms of the software application. Thepreferred phrasing is, “To complete business goal, follow these steps.”

• Two or more task steps, presented in an ordered list.

A task topic can also include the following additional information.

• A brief description. This might be added between the title and the context statement.

• Prerequisites. If a task has one or more prerequisites, such as use of a third party tool or access with an adminpassword, list them before step 1 of the procedure.

• The result of the task. Providing the expected result of a procedure is helpful to users, especially when thesteps are complex, there are multiple results such as status messages that occur over time, or users have severalchoices for what to do next.

For more information, see the Using This Task Template.

5.3.2 Example Task Topics

The Building and Running an edX Course guide contains these examples of task topics.

• Enable the Third Party Authentication Feature task presents a procedure that has just two steps.

• Decrypt an Encrypted File is a task that includes alternate procedures for Windows and Macintosh users andshows an illustration of the result of the task.

5.4 Using This Task Template

Typically, a task topic is added after a concept topic, so its title is a second level heading or lower.

For more information about concept topics, see Writing Concept Topics.

Replace or remove this sentence, and all other values within and including braces (), with your own text.

You can duplicate and use the source task_template.rst file to provide a starting point for your own tasktopics.

5.4.1 Title: Imperative a Noun

Optional description.

Before you begin this task, complete this list of prerequisites.

To provide the context for completing the task, follow these steps.

1. First step. Optional step result.

2. Second step.

Optional procedure result.

5.4. Using This Task Template 11

http://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/tpa/tpa_integrate_open/index.html#enable-the-third-party-authentication-feature

http://edx.readthedocs.io/projects/devdata/en/latest/access/credentials.html#decrypt-an-encrypted-file


12 Chapter 5. Topic Templates

CHAPTER 6

Style Conventions and Content Layout

The edX documentation is authored using reStructuredText markup syntax. For a description and complete documen-tation, see reStructuredText .

For a sample .rst file that contains examples of the markup used by the edX documentation team, see theedx-documentation/en_us/edx_style_guide/source/ExampleRSTFile.rst file.

13

http://docutils.sourceforge.net/rst.html


Item .rst Formatting Examples NotesBook or guide name *italic* Building and Running

an edX CourseWhen you provide the title of the guidein addition to a cross-reference to aspecific section or topic in the guide,link the section or topic and then placethe name of the guide in italics. Other-wise, make the title the cross referencelink instead of presenting it in italics.Translator guidance is that strings initalic font should be translated.

Code samples ``monospace`` The member fieldsof this dictionary aredisplay_nameand usage_key.

Use monospace markup only forstrings that should not be translated,including code, settings, commands,SQL table columns, and event names.For longer examples, such as XMLtemplates that include text that can betranslated, use the code block markupand include a comment for translatorswith explicit instructions... Translators: In thefollowing XML code block,do not translate any ..text that is between the< > characters.

<problem display_name=→˓"webGLDemo">In the image below, click→˓the cone.

Programming ele-ments

``monospace`` The event_typeparameter enablesdownstream process-ing.An XBlock mustset has_score toTrue.

Follow the same rules as for code sam-ples. Programming elements includeattributes, classes, events, functions,methods, parameters, and properties.Identify the element type on first men-tion. Element names only need an arti-cle when the text also includes the ele-ment type.

• Set the has_score property toTrue.

• Set has_score to True.• Incorrect: Set the has_score to

true.

Unnamed icons “brief description” Select “back 30 sec-onds” on the playbackbar.

In most cases, icons have mouseoverhelp text. If the icon has help text, usethat text as the name of the control anduse **bold** like other UI elements.

New term optional: link to glos-sary definition

This section pro-vides conceptual andprocedural infor-mation about using:ref:`teams_gìn your courses.

Add new terms to the glossary. If youwant to be sure that people understandhow you are using the term, provide alink to the glossary definition. Do notitalicize newly introduced terms.

User interface con-trols

**bold** From the Tools menu,select Import.In the discussion nav-igation pane, selectFilter messages likethis.

For more information about user inter-face controls in edX products, see Doc-umenting User Interface Interactions.Translator guidance is that strings inboldface font can be translated.

User input ``monospace`` In the Show Calcula-tor field, type true.

Follow the same rules as for code sam-ples. The assumption is that values pre-sented in monospace font must be en-tered exactly as documented, and thattranslated versions of the value are notacceptable.If the user input value can be trans-lated, add a “Translator:” comment tothat effect.

Variables Surround with braces().

. . . in the formatorg-course-run-site.mongo.

Avoid angle brackets (< >) because rSTuses angle brackets to identify XMLexamples.

14 Chapter 6. Style Conventions and Content Layout

CHAPTER 7

Images

Because the user interface can change rapidly and frequently, and because it is very expensive for translation teams tolocalize screen shots, the edX documentation team uses screen shot images sparingly.

7.1 Resources

These resources for screen captures (existing dummy courses with good data) are available on edX Edge.

• AA Introduction to Music Theory

• La Tierra Centroamericana

7.2 Guidelines for Adding Images

7.2.1 Messages

Avoid using a screen shot to show an error, warning, or informational message. Instead, just include the text of themessage as part of the procedure or concept. Message text should be enclosed in quotation marks.

If you choose to show message text in a code block, you must include a translator note in a comment immediatelybefore that element. For more information and an example, see Guidelines for Translators.

7.2.2 Colors

Use the edX pattern library to select colors for your image.

15

https://studio.edge.edx.org/course/sylviaX/TEST10/2014_T3

https://studio.edge.edx.org/course/edX/GEO101/2014_T1\T1\textgreater

http://ux.edx.org/design_elements/colors/


7.2.3 Browser Width

Before you take a screen shot, reduce the window width to avoid extra white space. Usually this means you narrow thewidth of your browser until the page is no longer responsive. However, you do have the aesthetic control over whenreducing the width of the intended image will have the effect of making the screen shot too long.

The following image has a lot of white space inside the component editor. To produce a better illustration of thecomponent editor, make the browser narrower.

Keep images flush with text in bulleted and ordered lists.

16 Chapter 7. Images


7.3 Capturing Screen Shots

You can use any tool you like to capture images.

If you use SnagIt, you can configure preferences to include a timing delay and specific on-screen objects, includingthe cursor, as well as setting keyboard shortcuts for different configurations. References to the edX documentationteam’s SnagIt Style Gallery follow.

If you use a Mac computer, you can use the built-in screen capture application to take screen shots. To capture part ofthe screen, follow these steps.

Note: This method does not capture the positioning of the cursor.

1. Press CMD + SHIFT + 4. The cursor changes to a crosshairs symbol.

2. Click and drag from one corner of the area you want to capture to the corner diagonally opposite, and let go ofthe mouse when you’ve captured the image you want.

7.3. Capturing Screen Shots 17


7.4 Editing Images

You can use any tool you like to edit images. Some guidelines for SnagIt are included here.

7.4.1 SnagIt Style Gallery

SnagIt 3.3.5 has a Style Gallery feature that saves the customizations that you make to borders, arrows, and so on foreasy reuse.

If you use SnagIt, note that the following .snagstyles files are included in the Images directory of this guide.

• arrows.snagstyles adds arrows in three edX base colors.

• color_fill.snagstyles adds three edX base colors.

• outline_shapes.snagstyles adds three outline shapes in each of the three edX base colors.

• numbered_callouts.snagstyles adds numbered callouts in three edX base colors.

To add these edX SnagIt styles to your SnagIt application, drag each .snagstyles file onto the SnagIt icon in the toolbarof your computer.

7.4.2 Borders

Add a border with the following characteristics to every image.

(In SnagIt: Effects > Border; In Photoshop: Cmd + a, Edit > Stroke)

• Opacity: 100%

• Size: 2pt

• Color: edX Grayscale Dark, rgb(79, 89, 93) #4F595D

In SnagIt, the first time you make these selections for a border, a new tile appears in the Style Gallery with thesecharacteristics. Save that new style (select its + icon) so that you can reuse it in the future.

7.4.3 File Size and Format

Save the file, without resizing, in .png format. You set the size in the document: see Image Sizes.

7.4.4 Annotations

When you use SnagIt to add arrows, boxes, or other indicators, they are added as vector-based images. You can savethese additions in a special SnagIt format so that you can edit them later: choose Save As > .snagproj format.

When all of your edits are complete and you are ready to publish, choose Save As > png. This will flatten the image.

Colors for Annotations

When you annotate screen shots, use the colors in the edX pattern library.

• For most additions, use edX Brand Secondary base, a dark pink (rgb(203, 89, 141), #CB598D).

• If another color is required, use edX Brand Primary base, a medium blue (rgb(0, 121, 188), #0079BC).


http://ux.edx.org/design_elements/colors/


Text in Annotations

If you want to annotate screen shots, instead of adding text to the image, use numbered identifiers and provide a legendin the .rst file with the descriptions.

For graphics that must include text, such as flowcharts, use a tool such as Adobe Photoshop that allows you to addindividually editable layers. When you are ready to add the text, create a layer in the image specifically for the text,and only text. Be sure to leave 30% extra surrounding space for expansion.

Text in annotations uses the Open Sans font. To install the Open Sans font, follow these steps.

1. Visit the Google Fonts page for Open Sans.

2. Under Choose the styles you want, select Normal 400.

3. (optional) Under Choose the character sets you want, select any character sets.

4. On the right side of the page, click the Download icon. Choose the .zip file option in the dialog box that opens.

5. Copy all of the unzipped .ttf files and move them to the Macintosh HD/Library/Fonts directory.

6. Close and reopen any application that you want to use the font in.

7.5 Adding an Image to a File

When you add an image to a file, include a directive with the following information.

• The image directive

• The image width

• Image alt text

.. image:: Images/HTMLEditor.png:width: 450:alt: An image of the HTML component in the visual editor.

7.5.1 Alt Text for Accessibility

The purpose of alt text is to serve as a functional equivalent for an image. Every image that you add to the edXdocumentation must have alt text that makes the purpose of the image clear to those who are using screen readers.

The following examples are of useful alt text.

:alt: Image of the feedback check mark and x from a student's point of view.

:alt: A stacked bar chart for three subsections. In one subsection, fewerthan a third of the students who started videos finished watching them.

The following examples are of alt text that is less useful.

:alt: Image of a multiple choice problem.

:alt: Example response.

When you write alt text, follow these guidelines.

• Quality and meaning are more important than brevity. However, length is a consideration, and some automatedtests produce warnings for text that is longer than about 20 characters.

7.5. Adding an Image to a File 19

https://www.google.com/fonts#UsePlace:use/Collection:Open+Sans


• Punctuate the alt text.

• To ensure that every image in an HTML file has alt text, try the Durham University Alt Text Checker.

• To find other accessibility issues in an HTML file, try the Web Accessibility Evaluation Tool.

7.5.2 Image Sizes

When you save a screen shot, do not reduce it in size. You can define the image width in the rst file.

.. image:: Images/descriptive_image_name.png:width: 600:alt: Alt text in punctuated sentences or phrases.

Full screen width 600Course pane 500Component editor 450Dialog box 300Sidebar 250Extra-wide screen 800

Full screen width

Course pane or Course Outline page


https://www.dur.ac.uk/cis/web/accessibility/tools/alttext/

http://wave.webaim.org/


Component editor

Dialog box



Sidebar

Extra-wide screen






CHAPTER 8

Guidelines for Writing Global English

We, the edX documentation team, have the privilege of writing for diverse audiences. Soon, our work will be translatedinto languages other than English, and reach an even broader set of readers. To prepare, we need to continue to applycore technical writing principles. We also need to expand our skill sets to follow guidelines that will make what wewrite even easier for a global audience to understand and translate.

• Global Examples

• Short Sentences

• Active Voice and Active Verbs

• Bulleted Lists

• Pronouns

• Mood

• Provide Context

• Word Choice

• Use (and Add to) the Glossary

• Contractions

• White Space

• Punctuation

• Abbreviations

• References to Explore

25


8.1 Global Examples

In addition to writing so that our text can be easily translated, remember that our audience is global, and make surethis is reflected in the examples that we use to illustrate concepts in our documentation. Use situations that people canrelate to regardless of their culture, and use example names and email addresses that represent diverse ethnicities.

8.2 Short Sentences

Write short sentences when possible. Long sentences can include problems. . .

• complex grammar

• complex use of tenses

• ambiguous pronouns

• long clauses

• complex modifier strings

Try to limit sentences to 20-30 words. Rule of thumb: if you run out of breath when you read a sentence aloud, it istoo long.

However!

• Do not damage clarity.

• Do not sacrifice the syntactic cues provided by definite and indefinite articles.

• Do not omit important information. Be explicit.

Example:

“Block open port on catheter fitting” could mean completely different things once the definite article is inserted.Compare “Block the open port on the catheter fitting.” to “Block open the port on the catheter fitting.

8.3 Active Voice and Active Verbs

Use the active voice.

Use active verbs. Avoid nominalizations (nouns made from verbs or adjectives) as they disguise the actors.

Example nominalizations:

utilization, operation, facilitation, activation, completion, reaction, improvement, movement, discovery,difficulty

Here’s an example of a sentence drafted in the passive voice, and how it was rewritten in the active voice.

Passive: This method is typically applied to free text fields, including discussion posts and wiki articles.

Active: EdX typically applies this method to free text fields, including discussion posts and wiki articles.

TBD: gerunds

TBD: verb-centric writing

26 Chapter 8. Guidelines for Writing Global English


8.4 Bulleted Lists

Write bulleted lists so that they are translatable.

Introduce the list with a complete sentence.

Do not use the bulleted points to complete an introductory sentence fragment.

Make sure each bulleted point can stand alone.

This approach might increase word count, but it decreases translation cost.

8.5 Pronouns

Avoid ambiguous pronouns, particularly impersonal pronouns. All kinds of words can sneak into use as pronouns.

Examples:

all, another, any, each, either, few, following, many, neither, none, one, other, rest, same, several, some,such, that, them, these, those

Ask “of what?”, “of which?”, or “as what?” when you use these words.

Example:

In order to sterilize a reusable product using an autoclave, it must first be properly cleaned and disinfected.

What must be cleaned and disinfected?

Avoid broad-reference pronouns.

Example:

Our new monitor has virtually no background noise, which should substantially reduce the number offalse positives.

8.6 Mood

Avoid the subjunctive mood. Native English speakers have trouble with it. Prefer the indicative and imperative moods.

8.7 Provide Context

Be sensitive to words that are used as both nouns and verbs, and provide context for them.

Examples:

Display it on the screen.

Change the scroll rate on the display.

8.8 Word Choice

Avoid jargon.

Avoid colloquialisms.

8.4. Bulleted Lists 27


Avoid humor.

Eliminate unusual non-technical words.

Examples:

and so forth, albeit, heretofore, whilst, . . .

Use nouns as nouns, and verbs as verbs. (More on that elsewhere!)

Beware of commonly used constructions that introduce ambiguity.

Examples:

Replace “For more information on. . . ” with “For more information about. . . ”

Replace “When the process completes, you can. . . ” with “After the process completes. . . ”

8.9 Use (and Add to) the Glossary

Use and maintain our glossary and internal list of preferred terms and phrases. Be consistent in terms used.

Example:

top, cap, and cover are translated and understood as three different things, not as the same thing.

8.10 Contractions

Avoid contractions. They introduce ambiguity, particularly ‘d and ‘s. Use other means to convey a friendly, informaltone.

8.11 White Space

Plan for expanded text. Expansion of 25% is common, so incorporate white space in flowcharts, blocks of text, UIstrings. . .

8.12 Punctuation

Avoid slashes. They introduce ambiguity.

Avoid em dashes. Putting non-restrictive relative clauses into separate sentences leads to simpler, clearer writing.

Do not use smart quotes or smart apostrophes. Prefer the straight versions.

8.13 Abbreviations

Avoid clipped terms.

Examples:

stat, spec, app, quotes, rep

Exception:



“The mobile app” is the correct term.

Avoid acronyms.

Do not use Latin abbreviations.

Do not use non-technical abbreviations.

8.14 References to Explore

The Global English Style Guide JR Kohl

Microsoft Manual of Style 4th ed.

8.14. References to Explore 29



CHAPTER 9

Media Accessibility

The edX documentation team is committed to providing resources that are accessible to everyone. The followinginformation was originally written by Mark Sadecki, the edX accessibility specialist, for course teams who need toprepare accessible media. Its content is also useful for writers who are preparing instructional videos and technicaldocumentation.

• Introduction

• Blindness

• Low Vision

• Deafness

• Hard of Hearing

• WCAG 2 AA Requirements for Media

• Audio Description

9.1 Introduction

Sometimes it can be helpful to start any discussion on media accessibility by dispelling common myths and talkingabout the challenges people with disabilities face when consuming media before talking about the solutions. Mark puttogether the following information about how people with disabilities consume media, what their challenges are, andhow authors can provide solutions.

9.2 Blindness

People who are blind cannot access the visual information contained in videos. Some would conclude that the visualmedium is inherently inaccessible to those who cannot see. However, audio and digital text are still very accessible.

31


In accessibility we often talk about “alternative content.” With regard to media, audio and text can easily serve asalternative content for the blind. Good alternative content is equivalent content. Content is equivalent to other contentwhen both fulfill the same function or purpose when presented to the user.

9.2.1 Things to Keep in Mind

Here are a few things to keep in mind when creating media for your courses.

• Vocalize any print that appears in your video.

• Explain visual events that are important to the context of the video. This will improve the quality of yourmaterial, ensuring that all students understand the significance of what they are observing.

• Avoid using phrases like “over here we have. . . ” or “this number. . . ” that rely on a visual cue to comprehend.

9.2.2 How These Techniques Can Benefit a Broader Audience

Learners are increasingly consuming media while performing other tasks, such as driving, doing household chores,and so on, and they may not be able to focus on the video content at all. Try listening to only the audio track fromyour video. Is the information presented “equivalent”?

Note: With regard to blindness, Mark feels that it is important to drive home the fact that if you do not vocalizeunspoken visual events that are important to understanding the video, you will trigger a requirement to provide audiodescriptions, which is both expensive and time consuming.

9.3 Low Vision

People with low vision can access some visual information. Depending on their visual ability, they might have specificissues such as difficulty discerning foreground information from background information, or discerning between col-ors. They may be unable to react quickly to transient information, and may have a narrow angle of view and so maynot detect key information presented temporarily where they are not looking, or in text that is moving or scrolling.

A person with low vision is likely to use screen magnification software. This means that they will only be viewing aportion of the screen, and so must manage tracking media content.

Others with low vision may have difficulty reading when text is too small, has poor background contrast, or whendecorative fonts or effects are used. Users with low vision often benefit from the same vocalization techniques used toprovide access to those who are blind.


• Make sure important visual content remains on the screen long enough to be processed.

• Consider contrast and lighting when choosing settings and adding visual content.

• Use as much of the viewport as possible to present information.

• Be consistent with the placement of important visual information.

32 Chapter 9. Media Accessibility



Multimedia is increasingly being consumed on mobile devices that have a very small viewport. Many of the techniquesmentioned above will benefit users who consume your content on a mobile device.

9.4 Deafness

People who are deaf generally cannot access the audio content of your media. As a result, an alternative format isrequired. On edX, this is provided through synchronized captions.


When creating timed-text caption files, be sure to include descriptions of audible, non-speech content that is importantto comprehending the video (such as [APPLAUSE], [BUZZER], [ASCENDING TONE]).

The text should “fulfill the same function or purpose” as the audio.


Captions are useful for those who do not speak the same language as the speaker in the video. Onscreen text is easierto comprehend than spoken words. Captions can also be translated into other languages very easily.

9.5 Hard of Hearing

People who are hard of hearing may be able to access some audio material, but might not be able to discern certaintypes of sound, and may miss any information presented as audio only if it contains frequencies they can’t hear, or ismasked by background noise or distortion. They may miss audio which is too quiet, or of poor quality. People withcochlear implants may not have issues with audio volume levels, but comprehension may be challenging if the mediaexperience is overwhelming. People who are deaf or hard of hearing may also read lips.


• Speak loudly and clearly.

• Try to face the camera as much as possible when speaking onscreen.

• Avoid background noise and/or music that competes with the primary audio.

9.6 WCAG 2 AA Requirements for Media

EdX is committed to satisfying the requirements defined in WCAG 2.0 Level AA. Excerpted below are the WCAG2.0 guidelines that refer specifically to media. The goal of any training done at edX should be to ensure that courseteams create content that satisfies these criteria.

9.6.1 Principle 1: Perceivable

Information and user interface components must be presentable to users in ways they can perceive.

9.4. Deafness 33

http://www.w3.org/TR/WCAG20/

http://www.w3.org/TR/WCAG20/


Guideline 1.1 Text Alternatives

Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as largeprint, braille, speech, symbols or simpler language.

1.1.1 Non-text Content

All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for thesituations listed below. (Level A)

• Time-Based Media: If non-text content is time-based media, then text alternatives at least provide descriptiveidentification of the non-text content. (Refer to Guideline 1.2 for additional requirements for media.)

• Guideline 1.2 Time-based Media: Provide alternatives for time-based media.

1.2.1 Audio-only and Video-only (Prerecorded)

For prerecorded audio-only and prerecorded video-only media, the following are true, except when the audio or videois a media alternative for text and is clearly labeled as such: (Level A)

• Prerecorded Audio-only: An alternative for time-based media is provided that presents equivalent informationfor prerecorded audio-only content.

• Prerecorded Video-only: Either an alternative for time-based media or an audio track is provided that presentsequivalent information for prerecorded video-only content.

1.2.2 Captions (Prerecorded)

Captions are provided for all prerecorded audio content in synchronized media, except when the media is a mediaalternative for text and is clearly labeled as such. (Level A)

1.2.3 Audio Description or Media Alternative (Prerecorded)

An alternative for time-based media or audio description of the prerecorded video content is provided for synchronizedmedia, except when the media is a media alternative for text and is clearly labeled as such. (Level A)

1.2.4 Captions (Live)

Captions are provided for all live audio content in synchronized media. (Level AA)

1.2.5 Audio Description (Prerecorded)

Audio description is provided for all prerecorded video content in synchronized media. (Level AA)



9.7 Audio Description

Most people are not familiar with audio descriptions. This video was made expressly to demonstrate both the needfor, and the level of detail required for, quality audio description. It also happens to be a good example of qualitycaptioning as well.

The Interviewer - Captions and Audio Descriptions

9.7. Audio Description 35

http://www.w3.org/TR/WCAG20/#audiodescdef

https://www.youtube.com/watch?v=rgRv4bSdLdU



CHAPTER 10

Working with edX Documentation Source Files

This section provides information about the tools used to create edX documentation, and gives guidelines for translat-ing or updating documentation in the edx-documentation GitHub repository.

For information, see the following topics.

• Documentation Tools and Processes

• Basic Formatting In .rst Files

• Guidelines for Translators

• Documentation Translation Process

See ExampleRSTFile.rst for examples of most of the formatting used in edX documentation files.

10.1 Documentation Tools and Processes

For information about the tools that the edX Documentation team uses to create documentation, see this wiki page:https://openedx.atlassian.net/wiki/display/DOC/Documentation+Tools

Our documentation source files are .rst (restructuredText) files. In addition to basic information that we provideabout working with our source files, you can find resources online, including the restructuredText Primer and http://docutils.sourceforge.net/rst.html#user-documentation.

Our documentation source files reside in a GitHub repository: edx-documentation. The folder structure within therepository is critical to our process and should not be modified. Each .rst file results in one page of HTML output.

For information about the folder structure, and creating folder for a new language, see Documentation TranslationProcess.

37

https://openedx.atlassian.net/wiki/display/DOC/Documentation+Tools

http://sphinx-doc.org/rest.html

http://docutils.sourceforge.net/rst.html#user-documentation

http://docutils.sourceforge.net/rst.html#user-documentation


10.2 Basic Formatting In .rst Files

This section covers .rst formatting most commonly used in our source files. For examples of the formatting explainedhere, refer to ExampleRSTFile.rst.

• Alignment

• Headings

• Lists

• Comments

• Special Tags

• Image Links

• Tables

• Anchors and Internal Links

• Code Examples

• Other Text Styles

10.2.1 Alignment

Formatting in .rst files relies on vertical alignment. Exact indents are important. Text that is on the same line as an .rsttag and text that is indented to the same level on following lines are interpreted as being part of the same block.

10.2.2 Headings

The level of a heading is indicated by a series of characters above and below the heading text.

• H1: pound symbols (#)

• H2: asterisk (*)

• H3: equals symbol (=)

For correct formatting, you must have the same number of the special tag characters above and below the heading text,and heading text cannot extend beyond the markers. If translated heading text is longer than the original English text,make sure to extend the markers so that they are at least the same length as translated text.

In addition to the first three levels of headings, up to three further levels can be defined, but are rarely used. Theseheading levels 4, 5, and 6 have a row of special characters only below the heading text. Like the top 3 heading levels,heading text cannot extend beyond the markers. If a translated heading is longer than the original, extend the markersto at least the same length as the translated heading.

• H4: asterisk (*)

• H5: equals symbol (=)

• H6: tilde (~)

A heading level that is defined by two rows of a particular special character above and below the heading text isinterpreted as being distinct from a heading level that uses that same character, but only below the heading text.

38 Chapter 10. Working with edX Documentation Source Files


10.2.3 Lists

Create automatic numbered lists using the hash symbol followed by a period, for each item in the numbered list. Forexample,

1. Select Advanced Settings.

2. Find the Course Advertised Start Date policy key.

3. Enter the value you want to display.

In some cases, for example if an automatic numbered list is interrupted by multiple paragraphs or a nested list, youneed to enter a number in place of the hash symbol to restart the numbered list at the correct number.

Create bulleted lists using the asterisk symbol followed by a period, for each item in the bulleted list. For example,

• Who is teaching the course?

• What university or college is the course affiliated with?

• What topics and concepts are covered in your course?

• Why should a learner enroll in your course?

For both numbered and bulleted lists, ensure that wrapped lines are indented to align with first character of text in thefirst line of each list item.

Note: Nested lists are supported, but should be checked carefully in output to make sure numbering or indented levelsare correct.

10.2.4 Comments

Lines beginning with 2 periods and a space indicate comments that are not visible in output. For example:

.. This is a comment.

10.2.5 Special Tags

Special tagging for notes, warnings, tables, and code blocks is achieved using lines beginning with 2 periods, followedby additional syntax.

.. note::

.. warning::

.. important::

.. list-table::

.. code-block::

10.2.6 Image Links

Images are included in documentation using special tagging and providing the path to the image file. Some imagelinks might have additional specifications such as height, width, or scale.

Alternative text for screen readers is required for each image. Provide text that is useful to someone who might not beable to see the image.

10.2. Basic Formatting In .rst Files 39


.. image:: ../../../shared/building_and_running_chapters/Images/about_page.png:alt: An image of the course summary page.

Important: When you translate existing content, make sure you do not change the filepath portion of the imagereference. You should only translate the alternative text.

If you replace any original source images with localized images, make sure the replacement image files have exactlythe same filenames, and replace them in the same Images folder location, so that image links within the documentationare not broken.

10.2.7 Tables

Tables are tagged using .. list-table::

Each table has the number of columns and their associated relative widths indicated in a width tag.

For proper formatting, the asterisk indicating each row must align vertically, and the hyphens indicating each columnmust also align. Empty cells must be accounted for, so that each column in a row is always marked, even if there is nocontent in the table cell. An example of an empty cell is the second column in the first row of the following example.

.. list-table:::widths: 25 25 50

* - .. image:: ../../../shared/building_and_running_chapters/Images/→˓AnnotationExample.png

:width: 100:alt: Example annotation problem

-- Annotation problems ask students to respond to questions about a

specific block of text. The question appears above the text when thestudent hovers the mouse over the highlighted text so that students canthink about the question as they read.

* - .. image:: ../../../shared/building_and_running_chapters/Images/PollExample.png:width: 100:alt: Example poll

- :ref:`Conditional Module`- You can create a conditional module to control versions of content that

groups of students see. For example, students who answer "Yes" to apoll question then see a different block of text from the students whoanswer "No" to that question.

* - .. image:: ../../../shared/building_and_running_chapters/Images/→˓JavaScriptInputExample.png

:width: 100:alt: Example JavaScript problem

- :ref:`Custom JavaScript`- Custom JavaScript display and grading problems (also called *customJavaScript problems* or *JS input problems*) allow you to create acustom problem or tool that uses JavaScript and then add the problem ortool directly into Studio.

For additional examples of tables, see the example .rst file



10.2.8 Anchors and Internal Links

Cross references use anchors that are placed above the heading for the target section. Anchors are defined in linesbeginning with 2 periods, followed by a space, underscore and the anchor text, and ending with a colon.

For example, .. _Anchors and Internal Links:

Note: Anchor text is never visible in output. It is replaced either by the actual text of the target heading, or by linktext that you explicitly specify. Do not edit or translate anchor text; if you do, the links will break.

Cross references using text of the target topic heading

For cross references that use the actual text of the target topic’s heading, use :ref:Ànchor_text` syntax. Forexample,

Ensure that your course introduction video follows the same:ref:`Compression Specifications` and :ref:`Video Formats` guidelines ascourse content videos

where “Compression Specifications” and “Video Formats” are the text for anchors that exist somewhere in the filesthat make up the guide. In output, the actual text of the associated headings is substituted.

In some cases where a file defining a list of links is used, you might see this alternative syntax for cross references,using an underscore after the second grave accent character instead of :ref:.

Ensure that your course introduction video follows the same`Compression Specifications`_ and `Video Formats`_ guidelines ascourse content videos

Note: For translations, make sure the substituted text reads well as part of the containing sentence. If necessary, addlink text to use instead of the actual heading text.

Cross references using specified link text

For cross references that use specific link text rather than substituting the actual target heading text, enter your owntext followed by the anchor text in angle brackets. For example,

For more information, see :ref:`the introductory section onexercises<Exercises_introduction>`

where Exercises_introduction is the anchor text that exists somewhere in the files that make up the guide,and “the introduction section on exercises” is your preferred link text.

For additional examples of cross-reference formatting, see the example .rst file.

10.2.9 Code Examples

Inline Code

In inline text, any text can be formatting as code (monospace font) by enclosing the selection within a pair of double“grave accent” characters. For example, these words are formatted in a monospace font when the documentation

10.2. Basic Formatting In .rst Files 41


is output as PDF or HTML.

Code Blocks

For larger blocks of code that are provided as examples in documentation, use the code-block tag. Here is a codeblock. For examples, see ExampleRSTFile.rst.

<problem><annotationresponse>

<annotationinput><text>PLACEHOLDER: Text of annotation</text><comment>PLACEHOLDER: Text of question</comment><comment_prompt>PLACEHOLDER: Type your response below:</comment_

→˓prompt><tag_prompt>PLACEHOLDER: In your response to this question,

→˓which tag belowdo you choose?</tag_prompt>

<options><option choice="incorrect">PLACEHOLDER: Incorrect answer (to

→˓make thisoption a correct or partially correct answer, change choice=

→˓"incorrect"to choice="correct" or choice="partially-correct")</option><option choice="correct">PLACEHOLDER: Correct answer (to make

→˓this optionan incorrect or partially correct answer, change choice="correct

→˓" tochoice="incorrect" or choice="partially-correct")</option><option choice="partially-correct">PLACEHOLDER: Partially

→˓correct answer(to make this option a correct or partially correct answer,change choice="partially-correct" to choice="correct" or choice=

→˓"incorrect")</option>

</options></annotationinput>

</annotationresponse><solution>PLACEHOLDER: Detailed explanation of solution

</solution></problem>

10.2.10 Other Text Styles

Boldface is used for labels that are visible in the user interface. The UI text is surrounded by double asterisks. Forexample, bold.

Italics are rarely used. Text surrounded by single asterisks is rendered in italics.

Monospace text is used for code examples. Text surrounded by double grave accent characters (‘‘) is rendered inmonospace font. Within the pair of double grave accents, further text formatting symbols is not recognized. For moreinformation, see Code Examples.

Warning: Make sure double quotation marks and apostrophes are straight (“) or (‘), not curly quotatation marksand apostrophes, which might be introduced when text is cut and pasted from other sources or editors.


CHAPTER 11

Guidelines for Translators

This section provides basic guidelines for translators of edX documentation. The complete edX documentation trans-lation process is described in Documentation Translation Process.

Important: Before you begin an edX documentation translation project, contact us at docs.edx.org to confirm thelanguage or languages that you are translating into, and so that we can make sure the repository is ready for you towork with.

To work on translations of edX documentation, you should have a basic understanding of reStructuredText and for-matting in .rst files. For more information and links to some resources, see Working with edX Documentation SourceFiles.

In addition, you or another person on the translation team should understand GitHub repositories and the GitHub pullrequest process. For more information about using GitHub, see https://help.github.com.

When you translate edX documentation source .rst files, follow these general guidelines. For examples of each typeof element, see the Example .rst file.

• What to Translate

• What Not to Translate

For information about working with edX documentation source files, see Working with edX Documentation SourceFiles.

For information about the documentation translation process, see Documentation Translation Process.

11.1 What to Translate

In addition to obvious text, do translate the following items.

43

https://help.github.com


• The text of notes and warnings. Translate text following the tags .. note::, .. important::, or ..warning::. Be careful to wrap and indent lines correctly, as described in Working with edX DocumentationSource Files.

• The link text in cross references. Link text is optional, so be sure to identify the difference between link text andanchor text if both are present in a cross reference. Only translate link text; if you translate anchor text, the linkwill be broken.

For example, in :ref:`Work with edX Documentation Source Files` the text between the ac-cent characters (‘) is the anchor text and should not be translated.

However, in the example :ref:`this is link text<Work with edX DocumentationSource Files>` link text is also present. The anchor text is between the angle brackets and shouldnot be translated. The text string between the first grave accent character and the opening bracket (“this is linktext”) is link text, and should be translated.

• The alt text for images. Translate text following the tag :alt: so that a useful description is provided forscreen readers.

An example of the formatting used to include an image follows.

.. image:: ../../../data/source/Images/DataCzar_Initialization.png:width: 100:alt: Flowchart showing process for initializing a data czar.

11.2 What Not to Translate

Do not translate or alter any of the following elements.

• The filenames and locations of any .rst files in the repository.

• The filenames and locations of any image files in the repository. If you replace any original source images withlocalized images, make sure the replacement image files have exactly the same filenames, and place them in thesame images folder location, so that image links within the documentation are not broken.

• Words in file paths in cross-references or image references.

• Words that are part of .rst directives, including note anf important. Examples are listed in Working withedX Documentation Source Files and ExampleRSTFile.

• The text of anchors in .rst files.

• Code examples that are tagged with .. code-block::.

• Variables, database field names, or code examples that are tagged with monospace code font (placed betweendouble grave accent characters).

For example, in the following sentence, do not translate the event names that are between pairs of double graveaccent characters.

The edX mobile app for iOS now emits ``play_video``, ``pause_video``, ``stop_video``,``load_video``, and ``seek_video`` events.

If a specific instance of one of these elements should be translated, the writer will include a translator note in acomment immediately before that element. An example follows.

.. Translators: the "msg" text that is included between the paragraph tags→˓can be translated.

::

44 Chapter 11. Guidelines for Translators


"correct": true,"score": 1,"msg": "The code passed all tests."

11.2. What Not to Translate 45


46 Chapter 11. Guidelines for Translators

CHAPTER 12

Documentation Translation Process

Important: Before you begin an edX documentation translation project, contact us at docs.edx.org to confirm thelanguage or languages that you are translating into, and so that we can make sure the repository is ready for you towork with.

To work on translations of edX documentation, you should have a basic understanding of reStructuredText and for-matting in .rst files. For more information, see Working with edX Documentation Source Files.

In addition, you or another person on the translation team should understand GitHub repositories and the GitHub pullrequest process. For more information about using GitHub, see https://help.github.com.

The basic process for translating edX documentation consists of these steps.

1. Use GitHub to clone the edx-documentation repository to a location on your local file system.

2. Locate the target language folder that we have set up for you. This is your working source directory. Languagefolders, including en_us, exist one level below edx-documentation. Each language folder mirrors theen_us folder.

Note: It is critical that you do not move or rename files within your target language folder as you work,otherwise you will break links and references.

3. Create a working branch or branches off master to make translation changes. Follow best practices for GitHubuse. For information, see https://help.github.com.

• Before making new branches, check that your local version of edx- documentation/master is up to date.

• On your branch(es), make edits to the source files using your preferred text editor.

– Save changes in the source files without renaming or moving the files.

– Commit changes back to GitHub.

– Create pull requests in GitHub for review purposes.

47




4. Build draft output and verify that everything renders as it should in both HTML and PDF formats. For informa-tion, see the “Verify Output” topic on this wiki page:

https://openedx.atlassian.net/wiki/display/DOC/Instructions+for+Updating+Documentation

5. Notify the edX Documentation team when you have changes ready for review and testing. The team can alsohelp you generate draft output for review and testing.

6. Make any revisions resulting from reviews and testing, then notify the edX Documentation team that the pullrequest is ready to merge into the repository.

7. The edX Documentation team merges translation pull requests into the repository.

8. The edX Documentation team updates and builds the readthedocs projects for the next release or a plannedfuture release.

For information about working with edX Documentation source files, see Working with edX Documentation SourceFiles.

For documentation translation guidelines, see Guidelines for Translators.

48 Chapter 12. Documentation Translation Process

https://openedx.atlassian.net/wiki/display/DOC/Instructions+for+Updating+Documentation

CHAPTER 13

Example .rst File

If you work with edX documentation source files, you might find this file helpful as a reference. This file containsexamples of .rst formatting.

Explanations and more context for each type of element are provided in Working with edX Documentation SourceFiles.

This file covers the following topics.

• Heading Levels

• Paragraph Text and Commented Text

• Ordered and Unordered Lists

• Conditional Text

• Notes and Warnings

• Cross-References

• Image References

• Tables

• Code Formatting

13.1 Heading Levels

#############Heading 1#############

*************Heading 2

49


*************

===========Heading 3===========

Heading 4

************

Heading 5===========

Heading 6~~~~~~~~~~~

13.2 Paragraph Text and Commented Text

This is an example of regular text in paragraph form. There are no indents. As a best practice, break lines at about 80characters, so that each line has its own line number for commenting in reviews.

Warning: Throughout text and code examples, make sure double quotation marks and apostrophes are straight(“) or (‘), not curly quotatation marks and apostrophes, which might be introduced when text is cut and pastedfrom other sources or editors.

Boldface is used for labels that are visible in the user interface. The UI text is surrounded by double asterisks. Forexample, bold.

Italics are rarely used. Text surrounded by single asterisks is rendered in italics.

Monospace text is used for code examples. Text surrounded by double grave accent characters is rendered inmonospace font.

.. comments can be added in a file by starting a line with 2 periods and aspace.

In English source files, look for comments addressed to translators from writers.

.. Translators: In this code example, do not translate such and such.

13.3 Ordered and Unordered Lists

Use hash symbols for ordered lists.

#. Select **Advanced Settings**.#. Find the **Course Advertised Start Date** policy key.#. Enter the value you want to display.

Note: Ordered lists usually use numerals. Nested ordered lists (ordered lists inside other ordered lists) use letters.

Use asterisks for unordered (bulleted) lists.

50 Chapter 13. Example .rst File


* Who is teaching the course?

* What university or college is the course affiliated with?

* What topics and concepts are covered in your course?

* Why should a learner enroll in your course?

13.3.1 Nested Lists or Content

You can include content including additional lists and code examples inside lists.

Unordered List inside Ordered List

To include an unordered list inside an ordered list, indent the unordered list three spaces. The first bullet in theunordered list must be flush with the text in the ordered list.

#. Review your entry to verify that the key is accurate and that it issurrounded by quotation marks. If there is a list of keys, they must becomma separated.

* In this example, the key for the Annotation Problem tool is the onlyvalue in the list.

* In this example, the key for the Annotation Problem tool is added atthe beginning of a list of other keys.

#. Select **Save Changes**.

Ordered List inside Unordered List

To include an ordered list inside an unordered list, indent the ordered list two spaces. The first number or letter of theordered list must be flush with the text in the unordered list.

* Review your entry to verify that the key is accurate and that it issurrounded by quotation marks. If there is a list of keys, they must be commaseparated.

#. In this example, the key for the Annotation Problem tool is the onlyvalue in the list.

#. In this example, the key for the Annotation Problem tool is added at thebeginning of a list of other keys.

* Select **Save Changes**.

13.3. Ordered and Unordered Lists 51


Unordered List inside Unordered List

To include an unordered list inside another unordered list, indent the second unordered list two spaces. The first bulletof the second unordered list must be flush with the text in the unordered list.

* Review your entry to verify that the key is accurate and that it issurrounded by quotation marks. If there is a list of keys, they must becomma separated.


#. In this example, the key for the Annotation Problem tool is added at thebeginning of a list of other keys.

* Select **Save Changes**.

Ordered List inside Ordered List

To include another ordered list inside an ordered list, indent the second ordered list three spaces. The second orderedlist must be flush with the text in the numbered list. The first ordered list uses numerals, and the second uses letters.

#. Review your entry to verify that the key is accurate and that it issurrounded by quotation marks. If there is a list of keys, they must becomma separated.


#. In this example, the key for the Annotation Problem tool is added atthe beginning of a list of other keys.

#. Select **Save Changes**.

Code, Images, and Other Content inside Lists

To include content such as code or an image inside a list, position the code or image directive flush with the text in thelist. That is, indent three spaces for ordered lists and two spaces for unordered lists.

#. In the ``lms.env.json`` and ``cms.env.json`` files, set the value of``CERTIFICATES_HTML_VIEW`` within the ``FEATURES`` object to ``true``.

.. code-block:: bash

"FEATURES":



...'CERTIFICATES_HTML_VIEW': true,...

#. Save the ``lms.env.json`` and ``cms.env.json`` files.

13.4 Conditional Text

To conditionalize a single paragraph, use either the only:: Partners or the only:: Open_edX directive,and indent the paragraph under the directive. You can add the conditional text as regular text or as a note.

Make sure to indent the paragraph under the directive.

.. only:: Partners

Data about course enrollment is available from edX Insights. You can accessInsights from the instructor dashboard for your live course: after you select

**Instructor**, follow the link in the banner at the top of each page. Formore information, see Ùsing edX Insights`_.

.. only:: Open_edX

.. note::If you want to require an entrance exam for your course, you also createthe exam in the course outline. Before you can create an exam, you mustset your course to require an entrance exam in Studio. For moreinformation, see :ref:`Require an Entrance Exam`.

To conditionalize more than a paragraph, use either the only:: Partners or the only:: Open_edX direc-tive, and then use an include:: directive indented under the only directive.

.. only:: Open_edX

.. include:: ../../../shared/building_and_running_chapters/running_course/Section_→˓course_student.rst

13.5 Notes and Warnings

.. note::This is note text. If note text runs over a line, make sure the lines wrapand are indented to the same level as the note tag. If formatting isincorrect, part of the note might not render in the HTML output.

Notes can have more than one paragraph. Successive paragraphs must indentto the same level as the rest of the note.

Note: This is note text. If note text runs over a line, make sure the lines wrap and are indented to the same level asthe note tag. If formatting is incorrect, part of the note might not render in the HTML output.

Notes can have more than one paragraph. Successive paragraphs must indent to the same level as the rest of the note.

13.4. Conditional Text 53


.. warning::Warnings are formatted in the same way as notes. In the same way, linesmust be broken and indented under the warning tag.

Warning: Warnings are formatted in the same way as notes. In the same way, lines must be broken and indentedunder the warning tag.

13.6 Cross-References

In edX documents, you can include cross-references to other locations in the same edX document, to locations in otheredX documents (such as a cross- reference from a location in the Building and Running an edX Course guide to alocation in the EdX Learner’s Guide), to JIRA stories, and to external websites. In this section, “EdX documents”refers to the resources, including guides and tutorials, that are listed on docs.edx.org.

For more information about creating cross-references using RST and Sphinx, see Cross-referencing arbitrary locationsin the online Sphinx documentation.

13.6.1 Cross-References to Locations in the Same Document

Cross-references to locations in the same document use anchors that are located above the heading for each topic orsection. Anchors can contain numbers, letters, spaces, underscores, and hyphens, but cannot include punctuation.Anchors use the following syntax.

.. _Anchor Text:

The following example shows an anchor for a section, followed by the heading for that section. SFD SN KeyboardShortcuts is the anchor text.

.. _SFD SN Keyboard Shortcuts:

******************************Keyboard Shortcuts for Notes

******************************

To create cross-references to locations in the same document, you can use the anchor only, or you can use your owntext. The anchor text is never visible in output. It is replaced by the text of the heading that follows the anchor or thetext that you specify.

Cross-References Using the Anchor Only

To add a cross-reference to a specific location in a document and use the text of the heading for that location as linktext, use :ref:Ànchor Text` syntax, as in the following example.

For more information about using keyboard shortcuts, see :ref:`SFD SNKeyboard Shortcuts`.

In this example, “SFD SN Keyboard Shortcuts” is the anchor text for a section that is titled “Keyboard Shortcuts forNotes”. Readers will see the following text, and “Keyboard Shortcuts for Notes” will be an active link.


http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations


For more information about using keyboard shortcuts, see Keyboard Shortcutsfor Notes.

Cross-References Using Specified Link Text

For internal cross-references that use text other than the heading for the section that you’re linking to, use:ref:`specified text<Anchor Text>` syntax, as in the following example.

If you want to, you can use :ref:`keyboard shortcuts<SFD SN KeyboardShortcuts>` to create, edit, and view notes.

Note: Do not include a space between the last word of the link text and the opening angle bracket for the anchor text.

In this example, “keyboard shortcuts” is the link text, and “SFD SN Keyboard Shortcuts” is the anchor text for asection that is titled “Keyboard Shortcuts for Notes”. Readers will see the following text, and “keyboard shortcuts”will be an active link.

If you want to, you can use keyboard shortcuts to create, edit, and view yournotes.

13.6.2 Cross-References to Locations in Different edX Documents

You can create cross-references between different edX documents. For example, you can create a link in Building andRunning an edX Course to a topic in the EdX Learner’s Guide. To do this, you use the intersphinx map ID of thedocument that you want to link to and the anchor text for the section you want. The cross-reference uses the followingsyntax.

:ref:ìntersphinx_map_ID:Anchor Name`

For example:

:ref:`partnercoursestaff:Release Dates`

To find the intersphinx map ID for the document that you want, follow these steps.

1. Open the conf.py file in the edx-documentation/shared folder, and then locate the following line.

intersphinx_mapping =

2. In the list that follows this line, find the ID for the document that you want. The text between the single quotationmarks (‘) at the beginning of each line is the intersphinx map ID for the document.

The following intersphinx map IDs are the most frequently used.

13.6. Cross-References 55

https://github.com/edx/edx-documentation/blob/master/shared/conf.py


Table 13.1: :widths: 25 25 50Map ID Documentpartnercoursestaff Building and Running an edX Courseopencoursestaff Building and Running an Open edX Courselearners EdX Learner’s Guideopenlearners Open edX Learner’s Guidedata EdX Research Guideinsights Using edX Insightsinstallation Installing, Configuring, and Running the Open edX Platformopendevelopers Open edX Developer’s Guidepartnerreleasenotes Partner release notesopenreleasenotes Open edX release notes

13.6.3 Cross-References to JIRA

For cross-references to JIRA tickets, use the :jira:`PROJECT-ticketnumber` syntax, as in the followingexample.

For more information, see :jira:`DOC-2316`.

Note that jira replaces ref for these links.

Readers will see the following text, and “DOC-2316” will be an active link.

For more information, see DOC-2316.

13.6.4 Cross-References to External Web Pages

A cross-reference to an external web page has several elements.

• The URL of the external web page.

• The text to use for the cross-reference. This text becomes an anchor in the file that contains the cross-reference.

• An include directive in the file that contains the cross-reference to the links.rst file that is located in theedx-documentation/en_us/links/ folder.

• An entry in the links.rst file.

To create an external cross-reference, follow these steps.

1. In the paragraph where you want the cross-reference, add the text that you want to use for the link, formatted asfollows (where “Release Pages” is the link text). This creates an anchor out of that text.

The edX engineering wiki `Release Pages`_ provide access to detailedinformation about every change made to the edx-platform GitHubrepository.

2. In the file that contains the cross-reference, add an include directive for the edx-documentation/en_us/links/links.rst file if one does not already exist. These include directives are typically atthe end of the file.

.. include:: ../../links/links.rst



Note: The path to the links.rst file depends on the location of the file where you are creating the link. Forexample, the path might be ../../../links/links.rst or ../links/links.rst.

3. In the edx-documentation/en_us/links/links.rst file, add an entry for the anchor text and theURL of the external website, formatted as follows. Make sure that the anchor text in this file matches the anchortext in the file that contains the cross-reference exactly, including capitalization.

.. _Release Pages: https://openedx.atlassian.net/wiki/display/ENG/→˓Release+Pages

Readers will see the following text. “Release Pages” will be an active link.

The edX engineering wiki Release Pages provide access to detailedinformation about every change made to the edx-platform GitHubrepository.

13.7 Image References

Image references look like this.

.. image:: /Images/Course_Outline_LMS.png:width: 100:alt: A screen capture showing the elements of the course outline in the LMS.

Image links can include optional specifications such as height, width, or scale. Alternative text for screen readers isrequired for each image. Provide text that is useful to someone who might not be able to see the image.

13.8 Tables

Each example in this section shows the raw formatting for the table followed by the table as it would render (if youare viewing this file as part of the Style Guide).

13.8.1 Example of a table with an empty cell

The empty cell is the second column in the first row of this table.

.. list-table:::widths: 25 25 50

* - Annotation Problem-- Annotation problems ask students to respond to questions about a

specific block of text. The question appears above the text when thestudent hovers the mouse over the highlighted text so that students canthink about the question as they read.

* - Example Poll- Conditional Module- You can create a conditional module to control versions of content that

groups of students see. For example, students who answer "Yes" to apoll question then see a different block of text from the students who

13.7. Image References 57


answer "No" to that question.

* - Example JavaScript Problem- Custom JavaScript- Custom JavaScript display and grading problems (also called *customJavaScript problems* or *JS input problems*) allow you to create acustom problem or tool that uses JavaScript and then add the problem ortool directly into Studio.

Annotation Problem Annotation problems ask students to respond to ques-tions about a specific block of text. The question ap-pears above the text when the student hovers the mouseover the highlighted text so that students can think aboutthe question as they read.

Example Poll Conditional Module You can create a conditional module to control versionsof content that groups of students see. For example, stu-dents who answer “Yes” to a poll question then see a dif-ferent block of text from the students who answer “No”to that question.

Exampel JavaScript Prob-lem

Custom JavaScript Custom JavaScript display and grading problems (alsocalled custom JavaScript problems or JS input prob-lems) allow you to create a custom problem or tool thatuses JavaScript and then add the problem or tool directlyinto Studio.

13.8.2 Example of a table with a header row

.. list-table:::widths: 15 15 70:header-rows: 1

* - First Name- Last Name- Residence

* - Elizabeth- Bennett- Longbourne

* - Fitzwilliam- Darcy- Pemberley

First Name Last Name ResidenceElizabeth Bennett LongbourneFitzwilliam Darcy Pemberley

13.8.3 Example of a table with a boldface first column

.. list-table:::widths: 15 15 70:stub-columns: 1

* - First Name



- Elizabeth- Fitzwilliam

* - Last Name- Bennett- Darcy

* - Residence- Longboure- Pemberley

First Name Elizabeth FitzwilliamLast Name Bennett DarcyResidence Longboure Pemberley

13.8.4 Example of a table with a cell that includes an unordered list

The blank lines before and after the unordered list are critical for the list to render correctly.

.. list-table:::widths: 15 15 60:header-rows: 1

* - Field- Type- Details

* - ``correct_map``- dict- For each problem ID value listed by `ànswers``, provides:

* ``correctness``: string; 'correct', 'incorrect'

* ``hint``: string; Gives optional hint. Nulls allowed.

* ``hintmode``: string; None, 'on_request', 'always'. Nulls allowed.

* ``msg``: string; Gives extra message response.

* ``npoints``: integer; Points awarded for this `ànswer_id``. Nulls allowed.

* ``queuestate``: dict; None when not queued, else ``key:'', time:''``where ``key`` is a secret string dump of a DateTime object in the form'%Y%m%d%H%M%S'. Nulls allowed.

* - ``grade``- integer- Current grade value.

* - ``max_grade``- integer- Maximum possible grade value.

13.8. Tables 59


Field Type Detailscorrect_map dict For each problem ID value listed by answers, provides:

• correctness: string; ‘correct’, ‘incorrect’• hint: string; Gives optional hint. Nulls allowed.• hintmode: string; None, ‘on_request’, ‘always’. Nulls allowed.• msg: string; Gives extra message response.• npoints: integer; Points awarded for this answer_id. Nulls al-

lowed.• queuestate: dict; None when not queued, else key:'',time:'' where key is a secret string dump of a DateTime ob-ject in the form ‘%Y%m%d%H%M%S’. Nulls allowed.

grade integer Current grade value.max_grade integer Maximum possible grade value.

13.9 Code Formatting

13.9.1 Inline code

In inline text, any text can be formatted as code (monospace font) by enclosing the selection within a pair of dou-ble “grave accent” characters (‘). For example, ``these words`` are formatted in a monospace font when thedocumentation is output as PDF or HTML.

13.9.2 Code blocks

To set text in a code block, end the previous paragaph with 2 colons, leave one line before the intended code block,and make sure the code block is indented beyond the first colon.

For example, this is the introductory paragraph::

and this is the code block following.

Alternatively, use the code-block tag. Optionally, indicate the type of code after the 2 colons in the tag, which resultsin the tags within the code block being displayed in different colors.

.. code-block:: xml

<problem><annotationresponse>

<annotationinput><text>PLACEHOLDER: Text of annotation</text><comment>PLACEHOLDER: Text of question</comment><comment_prompt>PLACEHOLDER: Type your response below:</comment_

→˓prompt><tag_prompt>PLACEHOLDER: In your response to this question,

→˓which tag belowdo you choose?</tag_prompt>

<options><option choice="incorrect">PLACEHOLDER: Incorrect answer (to

→˓make thisoption a correct or partially correct answer, change choice=

→˓"incorrect"



to choice="correct" or choice="partially-correct")</option><option choice="correct">PLACEHOLDER: Correct answer (to make

→˓this optionan incorrect or partially correct answer, change choice="correct

→˓" tochoice="incorrect" or choice="partially-correct")</option><option choice="partially-correct">PLACEHOLDER: Partially

→˓correct answer(to make this option a correct or partially correct answer,change choice="partially-correct" to choice="correct" or choice=

→˓"incorrect")</option>

</options></annotationinput>

</annotationresponse><solution>PLACEHOLDER: Detailed explanation of solution

</solution></problem>

13.9. Code Formatting 61



CHAPTER 14

Glossary

A - C - D - E - F - G - H - I - K - L - M - N - O - P - R - S - T - V - W - XYZ

Note: Most of the links to documentation provided in this glossary are to the Building and Running an edX Courseguide, for edX partners. Many of the same topics are available in the Open edX version of this guide, Building andRunning an Open edX Course.

14.1 A

AAC

Advanced audio coding (AAC) is an audio coding standard for digital audio compression. AAC is thestandard format for YouTube.

A/B test

See Content Experiment.

About page

The course page that provides potential learners with a course summary, prerequisites, a course video andimage, and important dates.

accessible label

In a problem component, you use special formatting to identify the specific question that learners willanswer by selecting options or entering text or numeric responses.

This text is referred to as the accessible label because screen readers read all of the text that you supply forthe problem and then repeat the text that is identified with this formatting immediately before reading theanswer choices for the problem. This text is also used by reports and Insights to identify each problem.

All problems require accessible labels.

For more information, see The Simple Editor.

63

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/index.html#document-index

http://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/latest/index.html#building-and-running-an-open-edx-course

http://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/latest/index.html#building-and-running-an-open-edx-course

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/glossary.html#content-experiment

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_problem.html#simple-editor


advanced editor

An OLX (open learning XML) editor in a problem component that allows you to create and edit any typeof problem. For more information, see The Advanced Editor.

Amazon Web Services (AWS)

A third-party file hosting site where course teams can store course assets, such as problem files and videos.If videos are posted on both YouTube and AWS, the AWS version of the video serves as a backup in casethe YouTube video does not play.

assignment type

The category of graded student work, such as homework, exams, and exercises. For more information,see Establishing a Grading Policy For Your Course.

14.2 C

CAPA problem

A CAPA (computer assisted personalized approach) problem refers to any of the problem types that areimplemented in the edX platform by the capa_module XBlock. Examples range from text input, dragand drop, and math expression input problem types to circuit schematic builder, custom JavaScript, andchemical equation problem types.

Other assessment methods are also available, and implemented using other XBlocks. An open responseassessment is an example of a non-CAPA problem type.

certificate

A document issued to an enrolled learner who successfully completes a course with the required passinggrade. Not all edX courses offer certificates, and not all learners enroll as certificate candidates.

For information about setting up certificates for your course, see Setting Up Certificates in Studio.

chapter

See Section.

checkbox problem

A problem that prompts learners to select one or more options from a list of possible answers. For moreinformation, see Checkbox Problem.

chemical equation response problem

A problem that allows learners to enter chemical equations as answers. For more information, see Chem-ical Equation Problem.

circuit schematic builder problem

A problem that allows learners to construct a schematic answer (such as an electronics circuit) on aninteractive grid. For more information, see Circuit Schematic Builder Problem.

closed captions

The spoken part of the transcript for a video file, which is overlaid on the video as it plays. To show orhide closed captions, you select the CC icon. You can move closed captions to different areas on the videoscreen by dragging and dropping them.

For more information, see Watching Videos on the edX Video Player.

codec

64 Chapter 14. Glossary

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_problem.html#advanced-editor

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/grading/index.html#grading-index

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/set_up_course/studio_add_course_information/studio_creating_certificates.html#setting-up-certificates

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/checkbox.html#checkbox

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/chemical_equation.html#chemical-equation

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/chemical_equation.html#chemical-equation

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/circuit_schematic_builder.html#circuit-schematic-builder

http://edx.readthedocs.io/projects/edx-guide-for-students/en/latest/SFD_video_player.html#video-player


A portmanteau of “code” and “decode”. A computer program that can encode or decode a data stream.

cohort

A group of learners who participate in a class together. Learners who are in the same cohort can commu-nicate and share experiences in private discussions.

Cohorts are an optional feature of courses on the edX platform. For information about how you enablethe cohort feature, set up cohorts, and assign learners to them, see Using Cohorts in Your Courses.

component

The part of a unit that contains your actual course content. A unit can contain one or more components.For more information, see Developing Course Components.

content experiment

You can define alternative course content to be delivered to different, randomly assigned groups of learn-ers. Also known as A/B or split testing, you use content experiments to compare the performance oflearners who have been exposed to different versions of the content. For more information, see Overviewof Content Experiments.

content library

See Library.

content-specific discussion topic

A category within the course discussion that appears at a defined point in the course to encourage questionsand conversations. To add a content- specific discussion topic to your course, you add a discussioncomponent to a unit. Learners cannot contribute to a content-specific discussion topic until the releasedate of the section that contains it. Content-specific discussion topics can be divided by cohort, so thatlearners only see and respond to posts and responses by other members of the cohort that they are in.

For more information, see Working with Discussion Components. For information about making content-specific discussion topics divided by cohort, see Setting up Discussions in Courses with Cohorts.

course catalog

The page that lists all courses offered in the edX learning management system.

course handouts

Course handouts are files you make available to learners on the Home page. For more information, seeAdding Course Updates and Handouts.

course mode

See enrollment track.

course navigation pane

The navigation frame that appears at one side of the Course page in the LMS. The course navigation paneshows the sections in the course. When you select a section, the section expands to show subsections.When you select a subsection, the first unit in that subsection appears on the course page.

See also Unit Navigation Bar.

Course page

The page that opens first when learners access your course. On the Course page, learners can view thecourse outline and directly access the course, either by clicking a specific section or subsection on theoutline, or by clicking the Start Course button (Resume Course if the learner has previously accessedthe course).

14.2. C 65

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohorts_overview.html#cohorts-overview

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/course_components.html#developing-course-components

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/content_experiments/content_experiments_overview.html#overview-of-content-experiments

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/content_experiments/content_experiments_overview.html#overview-of-content-experiments

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_discussion.html#working-with-discussion-components

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohorts_setup_discussions.html#set-up-discussions-in-cohorted-courses

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_assets/handouts_updates.html#adding-course-updates-and-handouts


The latest course update, such as a course welcome message, appears above the course outline. Links tovarious Course Tools including Bookmarks, Reviews and Updates appear at the side of this page. Thispage is a combination of the former Home and Courseware pages.

course run

A version of the course that runs at a particular time. Information about a course run includes start andend dates, as well as staff and the languages the course is available in. You can create a course run whenyou create a course.

course track


courseware

In OLX (open learning XML) and in data packages, “courseware” refers to the main content of yourcourse, consisting mainly of lessons and assessments. Courseware is organized into sections, subsections,units, and components. Courseware does not include handouts, the syllabus, or other course materials.

Note that the Course page was formerly called the Courseware page.

course-wide discussion topic

Optional discussion categories that you create to guide how learners find and share information in thecourse discussion. Course-wide discussion topics are accessed from the Discussion page in your course.Examples of course-wide discussion topics include Announcements and Frequently Asked Questions.Learners can contribute to these topics as soon as your course starts. For more information, see CreatingCourse Discussions and Create Course-Wide Discussion Topics.

If you use cohorts in your course, you can divide course-wide discussion topics by cohort, so that althoughall learners see the same topics, they only see and respond to posts and responses by other members of thecohort that they are in. For information about configuring discussion topics in courses that use cohorts,see Setting up Discussions in Courses with Cohorts.

custom response problem

A custom response problem evaluates text responses from learners using an embedded Python script.These problems are also called “write-your-own-grader” problems. For more information, see Write-Your-Own-Grader Problem.

14.3 D

data czar

A data czar is the single representative at a partner institution who is responsible for receiving course datafrom edX, and transferring it securely to researchers and other interested parties after it is received.

For more information, see the Using the edX Data Package.

discussion

The set of topics defined to promote course-wide or unit-specific dialog. Learners use the discussiontopics to communicate with each other and the course team in threaded exchanges. For more information,see Creating Course Discussions.

discussion component

Discussion topics that course teams add directly to units. For example, a video component can be followedby a discussion component so that learners can discuss the video content without having to leave the page.


http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/manage_discussions/discussions.html#discussions


http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/manage_discussions/discussions.html#create-coursewide-discussion-topics

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohorts_setup_discussions.html#set-up-discussions-in-cohorted-courses

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/custom_python.html#write-your-own-grader

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/custom_python.html#write-your-own-grader

http://edx.readthedocs.io/projects/devdata/en/latest/index.html#edx-research-guide



When you add a discussion component to a unit, you create a content-specific discussion topic. See alsoContent Specific Discussion Topic.

For more information, see Working with Discussion Components.

discussion thread list

The navigation frame that appears at one side of the Discussion page in the LMS. The discussion threadlist shows the discussion categories and subcategories in the course. When you select a category, the listshows all of the posts in that category. When you select a subcategory, the list shows all of the posts inthat subcategory. Select a post to read it and its responses and comments, if any.

dropdown problem

A problem that asks learners to choose from a collection of answer options, presented as a drop-down list.For more information, see Dropdown Problem.

14.4 E

edX101

An online course about how to create online courses. The intended audience for edX101 is faculty anduniversity administrators.

edX Edge

edX Edge is a less restricted site than edX.org. While only edX employees and consortium memberscan create and post content on edX.org, any users with course creator permissions for Edge can createcourses with Studio on studio.edge.edx.org, then view the courses on the learning management system atedge.edx.org.

edX Studio

The edX tool that you use to build your courses. For more information, see Getting Started with Studio.

embargo

An embargo is an official ban on trade or commercial activity with a particular country. For example,due to U.S. federal regulations, edX cannot offer certain courses (for example, particular advanced STEMcourses) on the edx.org website to learners in embargoed countries. Learners cannot access restrictedcourses from an embargoed country. In some cases, depending on the terms of the embargo, learnerscannot access any edX courses at all.

enrollment mode


enrollment track

Also called course mode, course track, course type, enrollment mode, or seat type.

The enrollment track specifies the following items about a course.

• The type of certificate, if any, that learners receive if they pass the course.

• Whether learners must verify their identity to earn a certificate, using a webcam and a photo ID.

• Whether the course requires a fee.

The edX platform offers the following enrollment tracks.

• audit: The default enrollment track. This track does not offer certificates, does not require identityverification, and does not require a course fee.

14.4. E 67

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_discussion.html#working-with-discussion-components

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/dropdown.html#dropdown

https://www.edx.org/course/overview-creating-edx-course-edx-edx101#.VIIJbWTF_yM

http://edge.edx.org

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/getting_started/CA_get_started_Studio.html#getting-started-with-studio


• verified: This enrollment track offers verified certificates to learners who pass the course, verifytheir identities, and pay a required course fee. A course that offers the verified enrollment track alsoautomatically offers a free non-certificate enrollment track.

• honor: This enrollment track offers an honor code certificate to learners who pass the course. Thistrack does not require identity verification and does not require a fee. Note, however, that as ofDecember 2015, edx.org no longer offers honor code certificates. For more information, see NewsAbout edX Certificates.

exercises

Practice or practical problems that are interspersed in edX course content to keep learners engaged. Ex-ercises are also an important measure of teaching effectiveness and learner comprehension. For moreinformation, see Adding Exercises and Tools.

export

A tool in edX Studio that you use to export your course or library for backup purposes, or so that you canedit the course or library directly in OLX format. See also Import.

For more information, see Export a Course or Export a Library.

14.5 F

forum

See Discussion.

fps

Frames per second. In video, the number of consecutive images that appear every second.

14.6 G

grade range

Thresholds that specify how numerical scores are associated with grades, and the score that learners mustobtain to pass a course.

For more information, see Set the Grade Range.

grading rubric

See Rubric.

14.7 H

H.264

A standard for high definition digital video.

Home page

See Course Page.

HTML component


http://blog.edx.org/news-about-edx-certificates?track=blog

http://blog.edx.org/news-about-edx-certificates?track=blog

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/index.html#exercises-and-tools-index

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/releasing_course/export_import_course.html#export-a-course

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/libraries.html#export-a-library

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/grading/grade_range.html#set-the-grade-range

http://edx.readthedocs.io/projects/xblock-tutorial/en/latest/glossary.html#course-page


A type of component that you can use to add and format text for your course. An HTML component cancontain text, lists, links, and images. For more information, see Working with HTML Components.

14.8 I

Image mapped input problem

A problem that presents an image and accepts clicks on the image as an answer. For more information,see Image Mapped Input Problem.

Import

A tool in Studio that you use to load a course or library in OLX format into your existing course orlibrary. When you use the Import tool, Studio replaces all of your existing course or library content withthe content from the imported course or library. See also Export.

For more information, see Import a Course or Import a Library.

instructor dashboard

A user who has the Admin or Staff role for a course can access the instructor dashboard in the LMS byselecting Instructor. Course team members use the tools, reports, and other features that are available onthe pages of the instructor dashboard to manage a running course.

For more information, see Managing a Running Course.

14.9 K

keyword

A variable in a bulk email message. When you send the message, a value that is specific to the eachrecipient is substituted for the keyword.

14.10 L

label

See Accessible Label.

LaTeX

A document markup language and document preparation system for the TeX typesetting program. In edXStudio, you can Import LaTeX Code into an HTML Component.

learning management system (LMS)

The platform that learners use to view courses, and that course team members use to manage learnerenrollment, assign team member privileges, moderate discussions, and access data while the course isrunning.

learning sequence

See Unit Navigation Bar.

left pane

See Course Navigation Pane.

14.8. I 69

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_html_component.html#working-with-html-components

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/image_mapped_input.html#image-mapped-input

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/releasing_course/export_import_course.html#import-a-course

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/libraries.html#import-a-library

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/manage_live_course/index.html#managing-live-course-index

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_html_component.html#import-latex-code


library

A pool of components for use in randomized assignments that can be shared across multiple courses fromyour organization. Course teams configure randomized content blocks in course outlines to reference aspecific library of components, and randomly provide a specified number of problems from that contentlibrary to each learner.

For more information, see Working with Content Libraries and Randomized Content Blocks.

live mode

A view that allows the course team to review all published units as learners see them, regardless of therelease dates of the section and subsection that contain the units. For more information, see ViewingPublished and Released Content.

LON-CAPA

The Learning Online Network with Computer-Assisted Personalized Approach e-learning platform. Thestructure of CAPA problem types in the edX platform is based on the LON-CAPA assessment system,although they are not compatible.

See also CAPA Problems.

14.11 M

math expression input problem

A problem that requires learners to enter a mathematical expression as text, such as e=m*c^2.

For more information, see Completing Mathematical and Scientific Assignments in the EdX Learner’sGuide.

MathJax

A LaTeX-like language that you use to write equations. Studio uses MathJax to render text input such asx^2 and sqrt(x^2-4) as “beautiful math.”

For more information, see Using MathJax for Mathematics.

module

An item of course content, created in an XBlock, that appears on the Course page in the edX learningmanagement system. Examples of modules include videos, HTML-formatted text, and problems.

Module is also used to refer to the structural components that organize course content. Sections, subsec-tions, and units are modules; in fact, the course itself is a top-level module that contains all of the othercourse content as children.

multiple choice problem

A problem that asks learners to select one answer from a list of options. For more information, seeMultiple Choice Problem.

14.12 N

NTSC

National Television System Committee. The NTSC standard is a color encoding system for analog videosthat is used mostly in North America.


http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/libraries.html#content-libraries

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/randomized_content_blocks.html#randomized-content-blocks

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/testing_courseware.html#view-published-content

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/testing_courseware.html#view-published-content

http://www.lon-capa.org/

http://edx.readthedocs.io/projects/edx-guide-for-students/en/latest/completing_assignments/SFD_mathformatting.html#math-formatting

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/mathjax.html#mathjax-in-studio

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/multiple_choice.html#multiple-choice


numerical input problem

A problem that asks learners to enter numbers or specific and relatively simple mathematical expressions.For more information, see Numerical Input Problem.

14.13 O

OLX

OLX (open learning XML) is the XML-based markup language that is used to build courses on the OpenedX platform.

For more information, see What is Open Learning XML?.

open response assessment

A type of assignment that allows learners to answer with text, such as a short essay and, optionally, animage or other file. Learners then evaluate each others’ work by comparing each response to a rubriccreated by the course team.

These assignments can also include a self assessment, in which learners compare their own responses tothe rubric, or a staff assessment, in which members of course staff evaluate learner responses using thesame rubric.

For more information, see Introduction to Open Response Assessments.

14.14 P

pages

Pages organize course materials into categories that learners select in the learning management system.Pages provide access to the course content and to tools and uploaded files that supplement the course.Links to each page appear in the course material navigation bar.

For more information, see Managing the Pages in Your Course.

PAL

Phrase alternating line. The PAL standard is a color encoding system for analog videos. It is used inlocations such as Brazil, Australia, south Asia, most of Africa, and western Europe.

partner manager

Each EdX partner institution has an edX partner manager. The partner manager is the primary contact forthe institution’s course teams.

pre-roll video

A short video file that plays before the video component selected by the learner. Pre-roll videos playautomatically, on an infrequent schedule.

For more information, see Add a Pre-Roll Video to Your edX Course.

preview mode

A view that allows you to see all the units of your course as learners see them, regardless of the unit statusand regardless of whether the release dates have passed.

For more information, see Previewing Draft Content.

problem component

14.13. O 71

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/numerical_input.html#numerical-input

http://edx.readthedocs.io/projects/edx-open-learning-xml/en/latest/what-is-olx.html#what-is-open-learning-xml

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html#open-response-assessments-2

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_assets/pages.html#adding-pages-to-a-course

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/video/create_preroll_video.html#adding-a-preroll-video

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/testing_courseware.html#preview-unpublished-content


A component that allows you to add interactive, automatically graded exercises to your course content.You can create many different types of problems.

For more information, see Working with Problem Components and Adding Exercises and Tools.

proctored exam

At edX, proctored exams are timed, impartially and electronically monitored exams designed to ensurethe identity of the test taker and determine the security and integrity of the test taking environment.Proctored exams are often required in courses that offer verified certificates or academic credit. Formore information, see Managing Proctored Exams.

program

A program is a collection of related courses. Learners enroll in a program by enrolling in any course thatis part of a program, and earn a program certificate by passing each of the courses in the program with agrade that qualifies them for a verified certificate.

Several types of program are available on edx.org, including MicroMasters, Professional Certificate, andXSeries programs.

program offer

A program offer is a discount offered for a specific program. The discount can be either a percentageamount or an absolute (dollar) amount.

Progress page

The page in the learning management system that shows learners their scores on graded assignments inthe course. For more information, see Checking Your Progress in a Course in the EdX Learner’s Guide.

14.15 Q

question

A question is a type of post that you or a learner can add to a course discussion topic to bring attention toan issue that the discussion moderation team or learners can resolve.

For more information, see Creating Course Discussions.

14.16 R

Research Data Exchange (RDX)

An edX program that allows participating partner institutions to request data for completed edx.orgcourses to further approved educational research projects. Only partner institutions that choose to par-ticipate in RDX contribute data to the program, and only researchers at those institutions can request datafrom the program.

For more information, see Using the Research Data Exchange Data Package.

rubric

A list of the items that a learner’s response should cover in an open response assessment. For moreinformation, see the Rubric topic in Introduction to Open Response Assessments.

See also Open Response Assessment.


http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_problem.html#working-with-problem-components

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/index.html#exercises-and-tools-index

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/proctored_exams/proctored_managing.html#managing-proctored-exams

http://edx.readthedocs.io/projects/edx-guide-for-students/en/latest/SFD_check_progress.html#sfd-check-progress


http://edx.readthedocs.io/projects/devdata/en/latest/rdx/index.html#research-data-exchange

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html#pa-rubric

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html#open-response-assessments-2


14.17 S

seat type


section

The topmost category in your course outline. A section can represent a time period or another organizingprinciple for course content. A section contains one or more subsections.

For more information, see Developing Course Sections.

sequential

See Subsection.

short description

The description of your course that appears on the edX Course List page.

For more information, see Course Short Description Guidelines.

simple editor

The graphical user interface in a problem component that contains a toolbar for adding Markdown format-ting to the text you supply. The simple editor is available for some problem types. For more information,see Editing a Problem in Studio.

single sign-on (SSO)

SSO is an authentication service that allows a user to access multiple related applications, such as Studioand the LMS, with the same username and password. The term SSO is sometimes used to refer to thirdparty authentication, which is a different type of authentication system. For information about third partyauthentication, see Third Party Authentication.

special exam

A general term that applies to proctored and timed exams in edX courses. See Timed Exam and ProctoredExam.

split test

See Content Experiment.

subsection

A division in the course outline that represents a topic in your course, such as a lesson or another organiz-ing principle. Subsections are defined inside sections and contain units.

For more information, see Developing Course Subsections.

14.18 T

text input problem

A problem that asks learners to enter a line of text, which is then checked against a specified expectedanswer.

For more information, see Text Input Problem.

timed exam

14.17. S 73

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/course_sections.html#developing-course-sections

https://www.edx.org/course-list

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/set_up_course/planning_course_information/description_guidelines.html#course-short-description-guidelines

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_problem.html#problem-studio-view

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/course_subsections.html#developing-course-subsections

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/text_input.html#text-input


Timed exams are sets of problems that a learner must complete in the amount of time you specify. When alearner begins a timed exam, a countdown timer displays, showing the amount of time allowed to completethe exam. If needed, you can grant learners additional time to complete the exam. For more information,see Offering Timed Exams.

third party authentication

A system-wide configuration option that allows users who have a username and password for one system,such as a campus or institutional system, to log in to that system and automatically be given access to theLMS. These users do not enter their system credentials in the LMS.

For more information about how system administrators can integrate an instance of Open edX with acampus or institutional authentication system, see Enabling Third Party Authentication.

transcript

A text version of the content of a video. You can make video transcripts available to learners.

For more information, see Step 2. Create or Obtain a Video Transcript.

14.19 U

unit

A unit is a division in the course outline that represents a lesson. Learners view all of the content in a uniton a single page.

For more information, see Developing Course Units.

unit navigation bar

The horizontal control that appears at the top of the Course page in the LMS. The unit navigation barcontains an icon for each unit in the selected subsection. When you move your pointer over one of theseicons, the name of the unit appears. If you have bookmarked a unit, the unit navigation bar includes anidentifying flag above that unit’s icon.

See also Course Navigation Pane.

14.20 V

VBR

Variable bit rate. The bit rate is the number of bits per second that are processed or transferred. A variablebit rate allows the bit rate to change according to the complexity of the media segment.

vertical

See Unit.

video component

A component that you can use to add recorded videos to your course.

For more information, see Working with Video Components.


http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/timed_exams.html#timed-exams

http://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/tpa/index.html#enabling-third-party-authentication

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/video/create_transcript.html#create-the-transcript

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/course_units.html#developing-course-units

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_components/create_video.html#working-with-video-components


14.21 W

whitelist

In edX courses, a whitelist is a list of learners who are being provided with a particular privilege. For ex-ample, whitelisted learners can be specified as being eligible to receive a certificate in a course, regardlessof whether they would otherwise have qualified based on their grade.

In the grade report for a course, whitelisted learners have a value of “Yes” in the Certificate Eligiblecolumn, regardless of the grades they attained. For information about the grade report, see Interpretingthe Grade Report.

wiki

The page in each edX course that allows both learners and members of the course team to add, modify,or delete content. Learners can use the wiki to share links, notes, and other helpful information with eachother. For more information, see Using the Course Wiki.

14.22 XYZ

XBlock

EdX’s component architecture for writing course components: XBlocks are the components that delivercourse content to learners.

Third parties can create components as web applications that can run within the edX learning managementsystem. For more information, see Open edX XBlock Tutorial.

XSeries

A set of related courses in a specific subject. Learners qualify for an XSeries certificate when they passall of the courses in the XSeries. For more information, see XSeries Programs.

14.21. W 75

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/student_progress/course_grades.html#interpret-the-grade-report

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/student_progress/course_grades.html#interpret-the-grade-report

http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_assets/course_wiki.html#course-wiki

http://edx.readthedocs.io/projects/xblock-tutorial/en/latest/index.html#open-edx-xblock-tutorial

https://www.edx.org/xseries

Date post:	26-Jun-2020
Category:	Documents
Upload:	others
View:	12 times
Download:	0 times