Fixes DOC-2073

en_us/edx_style_guide/source/index.rst

@@ -9,10 +9,11 @@ edX Style Guide
     preferred.rst
     wordlist.rst
     userinterface.rst
+    templates/index.rst
     formattinglayout.rst
     images.rst
     global_English.rst
-    templates/index.rst
+    media_accessibility.rst
     WorkingWithEdXDocSource.rst
     DocTranslationGuidelines.rst
     DocTranslationProcess.rst

en_us/edx_style_guide/source/intro.rst

@@ -4,10 +4,14 @@
 Introduction
 ############
 
-The doc team follows Microsoft Manual of Style for Technical Publications
-style in general, but defers to AP style where there are differences.
+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 and open
+source contributors around the world.
+
+The edX documentation team follows the *Microsoft Manual of Style*, 4th
+edition. Terms that are not covered by the *Microsoft Manual of Style*, and 
+company or team decisions about usage which differs from those the 
+manual are documented here.
 
-Need to add doc organizational guidelines, e.g. a template for documenting a
-procedure, a concept, etc. What does an overview section consist of?
 
-Provide or link to examples wherever possible.

en_us/edx_style_guide/source/media_accessibility.rst

@@ -0,0 +1,254 @@
+.. _Media Accessibility:
+
+######################
+Media Accessibility
+######################
+
+The edX documentation team is committed to providing resources that are
+accessible to everyone. The following information was originally written by
+Mark Sadecki, the edX accessibility specialist, for course teams who need to
+prepare accessible media. Its content is also useful for writers who are
+preparing instructional videos and technical documentation.
+
+.. contents:: 
+  :local:
+  :depth: 1
+
+*************
+Introduction
+*************
+
+Sometimes it can be helpful to start any discussion on media accessibility by
+dispelling common myths and talking about the challenges people with
+disabilities face when consuming media before talking about the solutions. Mark
+put together the following information about how people with disabilities
+consume media, what their challenges are, and how authors can provide
+solutions.
+
+*************
+Blindness
+*************
+
+People who are blind cannot access the visual information contained in videos.
+Some would conclude that the visual medium is inherently inaccessible to those
+who cannot see. However, audio and digital text are still very accessible. In
+accessibility we often talk about "alternative content." With regard to media,
+audio and text can easily serve as alternative content for the blind. Good
+alternative content is equivalent content. Content is equivalent to other
+content when both fulfill the same function or purpose when presented to the
+user.
+
+============================
+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 your material, 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.
+
+====================================================
+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 from your
+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 vocalize unspoken visual events that are
+ important to understanding the video, you will trigger a requirement to
+ provide :ref:`audio descriptions<Audio Description>`_, which is both expensive and time consuming.
+
+*************
+Low Vision
+*************
+
+People with low vision can access some visual information. Depending on their
+visual ability, they might have specific issues such as difficulty discerning
+foreground information from background information, or discerning between
+colors. They may be unable to react quickly to transient information, and may
+have a narrow angle of view and so may not 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 a portion 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 when decorative fonts or effects are used. Users
+with low vision often benefit from the same vocalization techniques used to
+provide access to those who are blind.
+
+============================
+Things to Keep in Mind
+============================
+
+* 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.
+
+====================================================
+How These Techniques Can Benefit a Broader Audience
+====================================================
+
+Multimedia is increasingly being consumed on mobile devices that have a very
+small viewport. Many of the techniques mentioned above will benefit users who
+consume your content on a mobile device.
+
+*************
+Deafness
+*************
+
+People who are deaf generally cannot access the audio content of your media. As
+a result, an alternative format is required. On edX, this is provided through
+synchronized captions. 
+
+============================
+Things to Keep in Mind
+============================
+
+When creating timed-text caption files, be sure to include descriptions of
+audible, non-speech content that is important to comprehending the video (such
+as [APPLAUSE], [BUZZER], [ASCENDING TONE]).
+
+The text should "fulfill the same function or purpose" as the audio.
+
+====================================================
+How These Techniques Can Benefit a Broader Audience
+====================================================
+
+Captions are useful for those who do not speak the same language as the speaker
+in the video. Onscreen text is easier to comprehend than spoken words. Captions
+can also be translated into other languages very easily.
+
+**************************
+Hard of Hearing
+**************************
+
+People who are hard of hearing may be able to access some audio material, but
+might not be able to discern certain types of sound, and may miss any
+information presented as audio only if it contains frequencies they can't hear,
+or is masked by background noise or distortion. They may miss audio which is
+too quiet, or of poor quality. People with cochlear implants may not have
+issues with audio volume levels, but comprehension may be challenging if the
+media experience is overwhelming. People who are deaf or hard of hearing may
+also read lips.
+
+============================
+Things to Keep in Mind
+============================
+
+* 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.
+
+*********************************
+WCAG 2 AA Requirements for Media
+*********************************
+
+EdX is committed to satisfying the requirements defined in WCAG 2.0 Level AA.
+Excerpted below are the `WCAG 2.0 guidelines`_ that refer specifically to
+media. The goal of any training done at edX should be to ensure that course
+teams create content that satisfies these criteria.
+
+=========================
+Principle 1: Perceivable
+=========================
+
+Information and user interface components must be presentable to users in ways
+they can perceive.
+
+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 large print, 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 the situations listed below. (Level
+A)
+
+* Time-Based Media: If non-text content is time-based media, then text
+  alternatives at least provide descriptive identification 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 video is 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 information for prerecorded audio-only content.
+
+* Prerecorded Video-only: Either an alternative for time-based media or an
+  audio track is provided that presents equivalent 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 media alternative 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 synchronized media, 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)
+
+.. _Audio Description:
+
+**************************
+Audio Description
+**************************
+
+Most people are not familiar with `audio descriptions`_. This video was made
+expressly to demonstrate both the need for, and the level of detail required
+for, quality audio description. It also happens to be a good example of quality
+captioning as well.
+
+`The Interviewer - Captions and Audio Descriptions`_
+
+.. _The Interviewer - Captions and Audio Descriptions: https://www.youtube.com/watch?v=rgRv4bSdLdU
+
+.. _audio descriptions: http://www.w3.org/TR/WCAG20/#audiodescdef
+
+.. _WCAG 2.0 guidelines: http://www.w3.org/TR/WCAG20/