Documentation Overview and Products

Introduction

The doc team seeks to create useful information for anyone who uses the edX platform—learners, educators, researchers, system admins, and developers. Our documentation is based roughly on audience, with one or more products that correspond to each one. For example, for our course authors audience, we have the Building and Running an edX Course guide. 

Because the documentation team's capacity has been limited, ownership and maintenance of some of these products has been transferred to other teams. The documentation team currently maintains documentation for all Learner, Educator, and Business teams, but does not cover any Infrastructure teams, including the Open Source and data teams. 

Specifically, the documentation team will continue to update the partner version of our educator and learner guides (Building and Running an edX Course and the EdX Learner's Guide) and any documentation for the business team. The documentation team does not currently maintain the Open edX versions of our educator and learner guides (Building and Running an Open edX Course and the Open EdX Learner's Guide).

If partner, learner, or business documentation needs updates, anyone in the organization—including program coordinators, partner managers, and course author support—can submit a JIRA ticket to the DOC project. The documentation team will prioritize these requests.

Other teams will use the information that the documentation team has provided to maintain their documentation products.

For more information, see Doc Team Work Information.

Documentation Product Owners

The following table lists each current documentation product, its audience, and its owner.  The table also includes links to information pages about each product.

For information about how to update documentation in Read the Docs, see Creating and Updating Documentation - RTD.

For information about how to update documentation in Zendesk Guide, see Creating and Updating Documentation - Zendesk Guide.

ProductAudiencePurpose and CommentsOwner
UI text and messagingCourse teams, learners

Provide guidance at the point of use that uses the same terminology as the documentation, and has no spelling or grammatical errors.

Documentation
UI text and messagingAll other audiences (edX internal, developers)
Team that builds the feature
Building and Running an edX CourseCourse teams (partners)

Guide both new and experienced course team members through the process of building and running a course, and inform course teams about available features.

Documentation audiences that rely on this guide are:

  • Partner Managers:  Direct course teams to the guide for answers to Studio questions.
  • Partner Support: Relies on this guide to answer course team questions and resolve tickets.
  • Training: Relies on this guide as the source of current Studio functionality in order to develop robust and accurate training materials.
Documentation
EdX Learner's GuideLearners on edx.org

Provide help for learners who have questions about topics including how to navigate through a course, how to complete course materials, and how to receive certificates.

The EdX Learner's Guide isn't as well-known as the Building and Running guide. Until October 2016, the only way for learners to find the guide was through Google searches or references to the guide in the course. Many course teams didn't know about the guide. With the addition of context-sensitive help in the LMS, views of the EdX Learner's Guide jumped over 4500% in a week.

Additionally, there is some overlap between the FAQs that the student support team maintains and the learner's guide. Derek Hixon (Deactivated), Alyssa Boehm, and Deb Chatigny (Deactivated) have begun meeting to discuss the best way to serve learners.

Documentation/Support (TBD)
VariousBusiness customersThe new Business team will require different kinds of docs than we've created before. For more information, see Enterprise Docs To Do.Documentation
Building and Running an Open edX CourseCourse teams (OE)

Guide both new and experienced course team members through the process of building and running a course, and inform course teams about available features.

This guide is nearly identical to the partner B&R guide, but has a few differences. Some features available on edx.org are not available on Open edX, and vice versa.

Note that as of November 2016, any partner course author information that also pertains to the Open edX course authors guide will be included in the Open edX guide, but any information that pertains exclusively to the Open edX course authors guide will not be included by default.

Open Source
Open edX Learner's GuideLearners on OE installations

Provide help for learners who have questions about topics including how to navigate through a course, how to complete course materials, and how to receive certificates.

This guide is nearly identical to the partner learner guide, but has a few differences. Some features available on edx.org are not available on Open edX, and vice versa.

Note that as of November 2016, any partner learner information that also pertains to the Open edX Learner's Guide will be included in the Open edX guide, but any information that pertains exclusively to the Open edX Learner's Guide will not be included by default.

Open Source
Installing, Configuring, and Running the Open edX PlatformOpen edX system administrators

Provide information for system administrators who want to run an instance of Open edX and allow course teams to create courses.

Feedback from the Open edX community has indicated that this guide has significant information gaps. The documentation team has not had the resources to create and maintain this guide satisfactorily.

Open Source
Release notes and portal announcementCourse teams (partners and OE), system administrators, developers

Provide regular (usually weekly) information to partner institutions and the Open edX community, including course teams, system administrators, and developers, about the latest updates to the platform.

Feedback from course teams and from the Open edX community indicates that the release notes do a good job of letting course authors know about changes that will affect them, but do not always include important changes that affect system administrators and developers.

Product
Product updateCourse teams (partners and OE), system administrators, developersProvide regular (monthly) information to partner institutions and the Open edX community, including course teams, system administrators, and developers, about the latest updates to the platform.Product
EdX Research GuideResearchers (data czars)

Provide in-depth information to data czars about all of the events and SQL tables in their data packages.

Feedback has indicated that this guide has historically proven useful and adequate for researchers.

Analytics
Using edX InsightsCourse teams

Provide information about the graphs and other visualized data in Insights to course teams.

Feedback has indicated that this guide has historically proven useful and adequate for researchers.

Documentation

Open edX Developer's Guide

Developers

Provide developers with the information they need to develop applications for edX.

Developer documentation includes individual IDA documentation.

Feedback from the Open edX community has indicated that Open edX developer documentation has significant information gaps. The documentation team has not had the resources to create and maintain this guide satisfactorily.

Additionally, developer information in general is scattered among various wikis, GitHub, and other locations.

Tools

API documentation

Developers

Provide information for anyone who needs to use an edX API.

API documentation includes the following products, among others.

  • Open edX XBlock API Guide
  • Open edX Data Analytics API
  • Open edX Platform APIs

As of November 2016, only a few APIs are public and documented, and the documentation for these APIs is fragile and breaks frequently. EdX does not have a strategy for publishing or documenting APIs.

The documentation team has not had the resources to maintain API documentation satisfactorily.

Open edX XBlock TutorialDevelopers

Provide developers with a step-by-step guide to building an XBlock for Open edX.

Feedback from the Open edX community has indicated that this tutorial has significant information gaps. Additionally, Open Craft has its own XBlock tutorial that seems to be more robust and accurate.

edX Open Learning XML GuideDevelopers

Provide developers with detailed information about Open Learning XML (OLX), edX's version of XML.

This guide has been in an alpha version for over a year and has significant information gaps.

The Partner and Open edX Portals

Other than for monthly product updates, the documentation team does not work with the partner or Open edX portals. For more information about the partner portal, contact Kate Venier (Deactivated). For more information about the Open edX portal, contact John Mark Walker (Deactivated)

Updating Documentation Products

The owner of a documentation product determines if a feature or change needs documentation, then either creates that documentation independently or requests help from the documentation team.

Determine Documentation Needs

In general, you can use the following checklist to determine whether a feature or change needs documentation. The page for each product has more information for that specific product.

  • Is documentation for this feature a contractual obligation?
  • Will this feature/change require action from the guide's audience? For example, will this change affect any settings that system administrators or developers depend on, or will this change affect the way system administrators operate an Open edX instance?
  • Will this feature/change be visible to the guide's audience, even if the feature/change doesn't require action? For example, time zone improvements caused course due dates and times to change automatically to a learner's new time zone. Previously, both the Building and Running guide and the EdX Learner's Guide specifically mentioned that all times were in UTC.
  • Will this feature/change provide a new opportunity for the guide's audience? For example, is the feature a new tool that course teams can (but aren't required to) use?
  • Will this feature/change cause new events or SQL tables to appear in data packages?

Update Documentation or Submit a Documentation Request

A doc product owner can update documentation independently or request help from the documentation team.

Update Documentation Independently

Creating or updating documentation generally involves creating a new branch from the edx-documentation master branch, finding or creating .rst source files, merging any changes to the master edx-documentation branch, and then building the updated documentation product on readthedocs. 

For more information, see Creating and Updating Documentation - RTD.

Note: The edX Help Center is authored in Zendesk. Contact the doc team for updates or inclusions to the help center.

Request Help from the Doc Team

The documentation team is happy to provide limited writing and editing services. When you request help from the team, you can write a draft of the documentation for the doc team to review, or you can provide enough information for the doc team to write the documentation. The documentation team will then prioritize the work.

To ask for help from the doc team, submit a JIRA ticket to the DOC project. Make sure that the ticket includes:

  • A due date. This is the date when the feature/change is expected to be live (meaning released and turned on—not, for example, behind a flag). If the due date is uncertain, provide a best guess.
  • The engineer who will review the documentation.
  • The product team member who will review the documentation.
  • The feature/change priority.
  • If you have written a draft, the location of the .rst files and/or a PR number.
  • If you have not written a draft, enough detailed information that the doc team can write a draft for you to review. This includes screen shots or a link to a sandbox.
  • Links to additional information about the feature/change, including presentations and wiki pages.