Background

The mission of the edX documentation team is ideally to provide all users of the edX and Open edX platform with the information they need to create and run courses, run the edX platform, and develop tools for the edX platform successfully. This mission includes providing timely information for a variety of edX audiences.

Audiences

Audiences for edX documentation include the following groups:

Course teams (partner and Open edX): Course teams need to know how to create and run courses using Studio, the LMS, and the Instructor Dashboard. They need to know about changes to the platform that affect their courses, and they want to know when new features are released that provide them with new ways to present course material. The documentation products for this audience are:
Learners (partner and Open edX): Learners need to know how to complete actions such as enrolling and unenrolling from courses, signing up for verified certificates, and receiving certificates. They also need to know how to enter numerical expressions in the calculator, numerical input problems, and math expression input problems. The documentation products for this audience are the EdX Learner's Guide and the Open edX Learner's Guide.
Researchers: Data czars want to know, on a granular level, how learners are interacting with the institution's courses. They need to know what events edX logs and what these events indicate. On a higher level, edX course teams want to know which videos and problems are effective and which are not so that they can change the content in their courses if necessary. The documentation products for this audience are the EdX Research Guide (for data czars) and Using edX Insights (for course teams).
Enterprise Administrators:
Enterprise Application Engineers (Integration):
edX Support:
edX Staff: One way to learn detailed and comprehensive information about our products and platform is to read the documentation! The documentation serves as an excellent companion to new employee onboarding, to better understand the products, and the functionality that they provide.
Open edX system administrators: Open edX system administrators need to know how to install and configure the Open edX platform, including services such as e-commerce. The documentation product for this audience is Installing, Configuring, and Running the Open edX Platform.
Open edX developers: Open edX developers need to know what edX code and other conventions are so that they can develop tools and features for the platform. They need to know specific details about Open Learning XML (OLX), the edX variety of XML. This audience has historically been the most underserved. The documentation products for this audience include the Open edX Developer's Guide, the Open edX XBlock Tutorial, and various IDA guides.
EdX API users: There are a variety of different edX API users.

Products

Workflow

Prior to September 2016, the documentation team had four members. Each member covered one or more engineering teams, including Analytics, ECOM, Open Source, Platform, Solutions, and TNL. Documentation team members attended various meetings for the teams they covered.

The team sought to create and maintain documentation for all audiences. The team found out about documentation needs in the following ways.

Meetings with members of the product team and engineering teams
JIRA tickets
Mailing lists such as edx-code and openedx-analytics
Channels such as Open edX Slack
Walk-up requests
Meetings with student support

In addition to new features and requests, the documentation team had a large backlog of tasks to improve existing documentation. The team pruned this backlog in summer 2016, but the backlog remains substantial.

Current Situation

Ideally, the documentation team would be able to serve all edX audiences fully. However, the documentation team is currently short-staffed, and cannot cover all audiences or products.

Audience and Products

In conjunction with a team consisting of stakeholders across the organization, the documentation team has made the following decisions about its current audience and products.

Because most edX revenue comes from partners, and this audience needs to know how to build rich learning experiences on the edX platform, the documentation team will focus primarily on documenting new features for partner course authors in Building and Running an edX Course. The documentation team will complete backlog tasks for the B&R guide as time permits.
The documentation team will continue to provide UI text for user-facing features.
The documentation might continue to maintain the EdX Learner's Guide. However, because this guide overlaps with student support FAQs, and the student support team has a better understanding of the needs of the learner community, the documentation team will work with the support team and members of the product team to determine the best way to serve this audience.
The team will transfer ownership of all other documentation products to different teams, including Installing, Configuring, and Running the Open edX Platform, the EdX Developer's Guide, analytics information, all API documentation, and release notes.
The documentation team will continue to add information to the Building and Running and Open edX Course guide and the Open edX Learner's Guide if the information also pertains to edX partner course authors and edx.org learners. However, the documentation team will not add Open edX-specific information to a guide unless a specific request is made.
The documentation team will provide information so that other teams can create documentation, and will be available for guidance. Other teams can request help from the documentation team, and the documentation team will prioritize these requests.

Documentation Team Priorities

Note In February 2017, teams in the product and engineering departments were reorganized around audiences: Learner, Educator, and Business. These teams roughly correspond to the former ECOM, TNL, and Enterprise teams. The engineering department also has an Infrastructure team.

The documentation team will cover, and remain embedded in, the Learner, Educator, and Business teams. The documentation team will not cover the Infrastructure team.

If the Building and Running an edX Course guide needs additional updates, anyone in the organization—including program coordinators, partner managers, and course author support—can submit a JIRA ticket. The documentation team will prioritize these requests.

The documentation team will not monitor Slack channels, mailing lists, or HipChat rooms other than those related to the Learner, Educator, or Business teams.

Documentation Procedures

The documentation team follows the procedures outlined in Creating and Updating Documentation - RTD. Other teams will use these same procedures to maintain their documentation products.

Future Possibilities

With a larger staff and/or additional content creation tools, the documentation team can cover audiences and products it has covered in the past, as well as potentially create additional communication channels and deliverables to better support our audiences.

Note: The following numbers are not cumulative.

With .5 additional team member, the documentation team can complete a substantial number of backlog tasks.
With .5 additional team member, the documentation team can again cover the EdX Research Guide and Using Edx Insights.
With .5 additional team member, the documentation team can seek additional opportunities to meet with course authors and other documentation consumers to discover how to make the documentation more effective.
With 1.5 additional team member, the documentation team can assess and fill gaps in Installing, Configuring, and Running the Open edX Platform.
With 2-3 additional team members, the documentation team can begin to create clear documentation for Open edX developers. The team would reorganize and fill gaps in the EdX Developer's Guide, update or archive the XBlock Tutorial, complete the OLX guide, and determine the best way to document existing and new IDAs. The team could also seek to organize and consolidate the resources on the Community Resources and Documentation page.

Doc Team Work Information