From e84c7a01984897bbe39d59f0e1c6106cf3a0837c Mon Sep 17 00:00:00 2001 From: Alison Hodges Date: Thu, 19 Jun 2014 09:26:50 -0400 Subject: [PATCH] Fixes: DOC-392, shared preface listing resources for different types of audiences --- .../course_authors/source/change_log.rst | 4 +- docs/en_us/course_authors/source/index.rst | 3 +- docs/en_us/course_authors/source/preface.rst | 1 + docs/en_us/course_authors/source/read_me.rst | 7 +- docs/en_us/data/source/index.rst | 1 + docs/en_us/data/source/preface.rst | 1 + docs/en_us/data/source/read_me.rst | 2 +- docs/en_us/developers/source/index.rst | 1 + docs/en_us/developers/source/preface.rst | 1 + docs/en_us/shared/preface.rst | 261 ++++++++++++++++++ 10 files changed, 275 insertions(+), 7 deletions(-) create mode 100644 docs/en_us/course_authors/source/preface.rst create mode 100644 docs/en_us/data/source/preface.rst create mode 100644 docs/en_us/developers/source/preface.rst create mode 100644 docs/en_us/shared/preface.rst diff --git a/docs/en_us/course_authors/source/change_log.rst b/docs/en_us/course_authors/source/change_log.rst index 9265370ffd..5139fd4c56 100644 --- a/docs/en_us/course_authors/source/change_log.rst +++ b/docs/en_us/course_authors/source/change_log.rst @@ -12,11 +12,13 @@ June, 2014 * - Date - Change + * - 06/20/14 + - Added a :ref:`Preface` with resources for course teams, developers, researchers, and students. * - 06/18/14 - In the :ref:`View and download student data` section, updated the example report to include the new User ID column. * - 06/17/14 - - Added :ref:`TOC Transcripts` section to :ref:`Working with Video Components`. + - Added :ref:`Video TOC` section to :ref:`Working with Video Components`. * - 06/06/14 - Added a description of email task workflow states to the :ref:`Launch` section. diff --git a/docs/en_us/course_authors/source/index.rst b/docs/en_us/course_authors/source/index.rst index 6b609afa59..20cffb5c72 100755 --- a/docs/en_us/course_authors/source/index.rst +++ b/docs/en_us/course_authors/source/index.rst @@ -12,6 +12,7 @@ Building and Running an edX Course :maxdepth: 2 read_me + preface change_log getting_started/index building_course/index @@ -19,4 +20,4 @@ Building and Running an edX Course exercises_tools/index releasing_course/index running_course/index - students/index \ No newline at end of file + students/index diff --git a/docs/en_us/course_authors/source/preface.rst b/docs/en_us/course_authors/source/preface.rst new file mode 100644 index 0000000000..53895c8473 --- /dev/null +++ b/docs/en_us/course_authors/source/preface.rst @@ -0,0 +1 @@ +.. include:: ../../shared/preface.rst \ No newline at end of file diff --git a/docs/en_us/course_authors/source/read_me.rst b/docs/en_us/course_authors/source/read_me.rst index a78c5e51a3..b791b27e81 100644 --- a/docs/en_us/course_authors/source/read_me.rst +++ b/docs/en_us/course_authors/source/read_me.rst @@ -2,11 +2,10 @@ Read Me ******* -The edX *Building a Course with edX Studio* documentation is created -using RST_ files and Sphinx_. You, the user community, can help update and revise -this documentation project on GitHub:: +The edX *Building and Running an edX Course* guide is created +using RST_ files and Sphinx_. You, the user community, can help update and revise this documentation project on GitHub:: - https://github.com/edx/edx-platform/tree/master/docs/course_authors/source + https://github.com/edx/edx-platform/docs/en_us/course_authors/source To suggest a revision, fork the project, make changes in your fork, and submit a pull request back to the original project: this is known as the `GitHub Flow`_. diff --git a/docs/en_us/data/source/index.rst b/docs/en_us/data/source/index.rst index 6d8a083f40..32d613adfd 100644 --- a/docs/en_us/data/source/index.rst +++ b/docs/en_us/data/source/index.rst @@ -8,6 +8,7 @@ This document is intended for researchers and data czars at edX partner institut :maxdepth: 2 read_me.rst + preface.rst internal_data_formats/change_log.rst internal_data_formats/data_czar.rst internal_data_formats/sql_schema.rst diff --git a/docs/en_us/data/source/preface.rst b/docs/en_us/data/source/preface.rst new file mode 100644 index 0000000000..53895c8473 --- /dev/null +++ b/docs/en_us/data/source/preface.rst @@ -0,0 +1 @@ +.. include:: ../../shared/preface.rst \ No newline at end of file diff --git a/docs/en_us/data/source/read_me.rst b/docs/en_us/data/source/read_me.rst index 417e920b5f..df40a0a466 100644 --- a/docs/en_us/data/source/read_me.rst +++ b/docs/en_us/data/source/read_me.rst @@ -6,7 +6,7 @@ The *edX Research Guide* is created using RST_ files and Sphinx_. You, the user community, can help update and revise this documentation project on GitHub:: - https://github.com/edx/edx-platform/tree/master/docs/course_authors/source + https://github.com/edx/edx-platform/docs/en_us/data/source To suggest a revision, fork the project, make changes in your fork, and submit a pull request back to the original project: this is known as the `GitHub Flow`_. diff --git a/docs/en_us/developers/source/index.rst b/docs/en_us/developers/source/index.rst index ea852221a3..e98248c4f3 100644 --- a/docs/en_us/developers/source/index.rst +++ b/docs/en_us/developers/source/index.rst @@ -15,6 +15,7 @@ Contents: :maxdepth: 2 change_log + preface.rst overview.rst extending_platform/index xblocks.rst diff --git a/docs/en_us/developers/source/preface.rst b/docs/en_us/developers/source/preface.rst new file mode 100644 index 0000000000..53895c8473 --- /dev/null +++ b/docs/en_us/developers/source/preface.rst @@ -0,0 +1 @@ +.. include:: ../../shared/preface.rst \ No newline at end of file diff --git a/docs/en_us/shared/preface.rst b/docs/en_us/shared/preface.rst new file mode 100644 index 0000000000..01972aa41a --- /dev/null +++ b/docs/en_us/shared/preface.rst @@ -0,0 +1,261 @@ +.. _Preface: + +############ +Preface +############ + +Course teams, researchers, developers, students: the edX community includes +groups with a range of reasons for using the platform and objectives to +accomplish. To help members of each group learn about what edX offers, reach +goals, and solve problems, edX provides a variety of information resources. + +To help you find what you need, browse the edX offerings in these categories: + +* :ref:`Resources for Course Teams` +* :ref:`Resources for Researchers` +* :ref:`Resources for Developers` +* :ref:`Resources for Students` + +All members of the edX community are encouraged to make use of any of the +resources described in this preface. + +*********************** +System Status +*********************** + +For system-related notifications from the edX operations team, including +outages and the status of error reports. On Twitter_, you can follow +@edxstatus. + +Current system status and the uptime percentages for edX servers, along with +the Twitter feed, are published on the edX Status_ web page. + +.. _Resources for Course Teams: + +************************** +Resources for Course Teams +************************** + +Course teams include faculty, instructional designers, course staff, discussion +moderators, and others who contribute to the creation and delivery of courses +on edx.org or edX Edge. + +Documentation +------------- + +Documentation for course teams is available on the docs.edx.org web page. + +* *Building and Running an edX Course_* is a comprehensive guide with concepts + and procedures to help you build a course in edX Studio, and then use the + Learning Management System (LMS) to run a course. + + When you are working in edX Studio, you can access relevant sections of this + guide by clicking **Help** on any page. + +* *edX Course Staff Release Notes_* summarize the changes in each new version + of the edX Studio and LMS software. + +* *Creating a Peer Assessment_* describes features for students to provide + peer- and self- evaluations of responses to a question. Note that this new + feature is in limited release. + +These guides open in your web browser. The left side of each page includes a +**Search docs** field and links to that guide's contents. To open or save a PDF +version, click **v: latest** at the lower left of the page, then click **PDF**. + +Email +----- + +To receive and share information by email, course team members can: + +* Sign up to receive monthly newsletters_. + +* Sign up to receive release_ notes for every release. + +* Join the openedx-studio Google group_ to ask questions and participate in + discussions with peers at other edX partner organizations and edX staffers. + +Wikis and Web Sites +------------------- + +The edX product team maintains the OpenEdX Product_ wiki, which includes the +Open edX Public Product Roadmap_. + +The edX Author Support_ site hosts discussions that are monitored by edX +staffers. + +.. _Resources for Researchers: + +************************** +Resources for Researchers +************************** + +Data for the courses on edx.org and edX Edge is available to the "data czars" +at our partner institutions, and then used by database experts, statisticians, +educational investigators, and others for educational research. + +Documentation +------------- + +The *edX Research_ Guide* is available on the docs.edx.org web page. + +This guide opens in your web browser, with a **Search docs** field and links to +that guide's contents on the left side of each page. To open or save a PDF +version, click **v: latest** at the lower left of the page, and then click +**PDF**. + +Email +------- + +To receive and share information by email, researchers can join_ the openedx- +analytics Google group to ask questions and participate in discussions with +peers at other edX partner organizations and edX staffers. + +Wiki +------------------- + +The edX Analytics team maintains the Open edX Analytics_ wiki, which includes +links to periodic release notes, the Open edX Public Product Roadmap, and other +resources for researchers. + +.. _Resources for Developers: + +************************** +Resources for Developers +************************** + +Software engineers, system administrators, and translators work on extending +and localizing the code for the edX platform. + +Documentation +------------- + +Documentation for developers is available on the docs.edx.org web page. + +* *edX Developer_ Documentation* collects information directly from edX + platform python docstrings. The topics in this guide include guidelines for + contributing to Open edX, options for extending the Open edX platform, using + the edX public sandboxes, instrumenting analytics, and testing. + +* *Installing, Configuring, and Running the edX Platform_* provides procedures + for getting an edX developer stack (Devstack) and production stack + (Fullstack) oprerational. + +* *XBlock_: Open edX courseware components* provides preliminary documentation + on the XBlock component architecture for building courses. + +GitHub +------- + +There are two main edX repositories on GitHub. + +* The edx/edx-platform repo contains the code_ for the edX platform. + +* The edx/configuration repo_ contains scripts to set up and operate the edX + platform. + +Additional repositories are used for other projects. Our contributor agreement, +contributor guidelines and coding conventions, and other resources are +available in these repositories. + +Email and IRC +-------------- + +To receive and share information by email, developers can join these Google +groups to ask questions and participate in discussions with peers and edX +staffers. + +* For conversations about the code in Open edX, join `edx-code`_. +* For conversations about running Open edX, join `openedx-ops`_. +* For conversations about globalization and translation, join `openedx-translation`_. + +Additional Google groups are occasionally formed for individual projects. + +.. note:: Please do not report security issues in public. If you have a concern, please email security@edx.org. + +EdX engineers often monitor the Freenode #edx-code IRC channel. + +Wikis and Web Sites +------------------- + +The code.edx.org web site_ is an entry point for new contributors. + +The edX Engineering team maintains the Open Source_ Home wiki, which provides +insights into the plans, projects, and questions that the edX Open Source team +is working on with the community. + +The pull request dashboard_ is a visualization of the count and age of the +pull requests (PRs) assigned to teams at edX. Click the bars in this chart to +get more information about the PRs. + +.. _Resources for Students: + +************************** +Resources for Students +************************** + +In a Course +------------ + +All edX courses have a discussion forum where you can ask questions and +interact with other students and with the course team: click **Discussion**. +Many courses also offer a wiki for additional resources and materials: click +**Wiki**. + +Other resources may also be available, such as a course-specific facebook page +or twitter feed or opportunites for Google hangouts. Be sure to check the +**Course Info** page for your course as well as the **Discussion** and **Wiki** +pages. + +From time to time, the course team may send email messages to all students. +While you can opt out of these messages, doing so means that you may miss +important or time-sensitive information. To change your preferences for course +email, click **edX** or **edX edge** at the top of any page. On your dashboard +of current courses, locate the course and then click **Email Settings**. + +From edX +--------- + +To help you get started with the edX learning experience, edX offers a course +(of course!). You can find the edX Demo_ course on the edX web site. EdX also +maintains a list of frequently_ asked questions and answers. + +If you still have questions or suggestions, you can get help from the edX +support team: click **Contact** at the bottom of any edX web page or send an +email message to info@edx.org. + +For opportunities to meet others who are interested in edX courses, check the +edX Global Community meetup_ group. + + + +.. _Course: http://edx.readthedocs.org/projects/edx-partner-course-staff/en/latest/ +.. _Notes: http://edx.readthedocs.org/projects/edx-release-notes/en/latest/ +.. _Assessment: http://edx.readthedocs.org/projects/edx-open-response-assessments/en/latest/ +.. _Research: http://edx.readthedocs.org/projects/devdata/en/latest/ +.. _newsletters: http://edx.us5.list-manage.com/subscribe?u=1822a33c054dc20e223ca40e2&id=aba723f1aa +.. _release: http://edx.us5.list-manage2.com/subscribe?u=1822a33c054dc20e223ca40e2&id=83e46bd293 +.. _group: http://groups.google.com/forum/#!forum/openedx-studio +.. _Twitter: http://twitter.com/edXstatus/status/475026709256101888 +.. _Status: http://status.edx.org/ +.. _Product: https://edx-wiki.atlassian.net/wiki/display/OPENPROD/Open+edX+Product+Home +.. _Roadmap: https://edx-wiki.atlassian.net/wiki/display/OPENPROD/Open+edX+Public+Product+Roadmap +.. _Support: http://help.edge.edx.org/home +.. _join: http://groups.google.com/forum/#!forum/openedx-analytics +.. _Analytics: http://edx-wiki.atlassian.net/wiki/display/OA/Open+edX+Analytics+Home +.. _blog: http://engineering.edx.org/ +.. _email: http://groups.google.com/forum/#!forum/edx-code +.. _Source: http://edx-wiki.atlassian.net/wiki/display/OS/Open+Source+Home +.. _XBlock: http://edx.readthedocs.org/projects/xblock/en/latest/ +.. _Platform: http://edx.readthedocs.org/projects/edx-installing-configuring-and-running/en/latest/ +.. _Developer: http://edx.readthedocs.org/projects/userdocs/en/latest/ +.. _repo: http://github.com/edx/configuration/wiki +.. _site: http://code.edx.org/ +.. _code: https://github.com/edx/edx-platform +.. _dashboard: http://dash.openedx.org/age.html +.. _Demo: http://www.edx.org/course/edx/edx-edxdemo101-edx-demo-1038 +.. _frequently: http://www.edx.org/student-faq +.. _meetup: http://www.meetup.com/edX-Global-Community/ +.. _openedx-ops: http://groups.google.com/forum/#!forum/openedx-ops +.. _openedx-translation: http://groups.google.com/forum/#!forum/openedx-translation +.. _edx-code: http://groups.google.com/forum/#!forum/edx-code