This page is to capture processes to ensure documentation is kept up-to-date with any product changes initiated by non-edX employees.
Types of Documentation
There are two main types of documentation of concern to the Open edX community:
- GitHub Wikis. The wikis for any GitHub project are open to contributions by anyone working in the project. The wiki content is not managed in any way by the edX Documentation team. The wikis are a "free" area for developers to communicate as desired.
- "Official" edX Documentation. This is documentation sourced in RST files in the docs directories of edX projects, and published as edX documentation. The Open edX documentation owner manages this content. The guidelines below only concern this type of documentation.
Documentation Updates from Open edX
Open edX contributors are encouraged to update documentation for any code changes they make.
We need to add specific instructions for updating documentation to the edX Developer documentation.
Some non-edX contributors, such as at university partners, may have access to edX JIRA. In this case, they can directly create JIRA tasks for documentation. See the doc JIRA process.
The Open edX documentation owner will review any documentation updates, and merge directly or modify as appropriate. To find the Open edX documentation owner, see Documentation Products.
Open edX Pull Requests
For any Pull Request for changes made outside of edX, if there are any changes to files with the docs directory, the Open edX documentation owner should be tagged. The Open edX contributor can make this tag (as will be documented), or the edX reviewer should.
Pull Requests that do not included changes to files in the docs directory may still have documentation impact. Impacted documentation may include content for developers, researchers, course staff, or students. Unless engineering is sure there is no documentation impact, the Open edX documentation owner should be tagged. Again, the Open edX contributor or edX engineering can do this.
The Open edX documentation owner will review those pull requests, ask follow up questions as needed, and create appropriate documentation tasks in JIRA. Those tasks will be prioritized and addressed as any other task.
The Open edX documentation owner will monitor the edx-code group and the edx-code IRC channel and when there are questions from the community that should be answered in documentation, the team will create JIRA tasks to provide that documentation. The team will answer questions in those forums, or point to existing documentation, when feasible.