Doc Team Work Information
For more information, see the following pages.
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
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.
| Product | Audience | Purpose and Comments | Owner |
|---|---|---|---|
| UI text and messaging | Course 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 messaging | All other audiences (edX internal, developers) | Team that builds the feature | |
| Building and Running an edX Course | Course 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:
| Documentation |
| EdX Learner's Guide | Learners 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 (Deactivated), and Deb Chatigny (Deactivated) have begun meeting to discuss the best way to serve learners. | Documentation/Support (TBD) |
| Various | Business customers | The 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 Course | Course 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 Guide | Learners 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 Platform | Open 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 announcement | Course 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 update | Course teams (partners and OE), system administrators, developers | Provide 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 Guide | Researchers (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 Insights | Course 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 |
| 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 | |
| Developers | Provide information for anyone who needs to use an edX API. API documentation includes the following products, among others.
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 Tutorial | Developers | 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 Guide | Developers | 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).
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.