For more information, see the following pages.
...
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.