The documentation team relies on the knowledge of subject matter experts (SMEs) to produce accurate and complete documentation that is suitable for use by its intended audience. We ask SMEs across edX teams, and sometimes externally, to review documentation before it's released publicly.
Reviewers are asked to comment on the accuracy and completeness of the documentation draft. Here are a few guidelines that might be useful to keep in mind.
- Are the procedures accurate? That is, are any prerequisites stated, all necessary steps provided, and are they presented in the correct sequence?
- Is the conceptual information that accompanies the procedures adequate? Does it introduce the feature in terms of the problems it solves, or the use cases that it fulfills? Is it too detailed, or not detailed enough?
- Will the intended audience (course teams, learners, developers, or researchers) be able to follow the information as it is? That is, do they actually have the level of background knowledge assumed by the documentation?
The doc team follows this tech review process.
- The member of the doc team submits new or changed document for review in one of the following ways.
- Submits a pull request for the changes, and uses the Doc Team Pull Request Template to identify and tag SMEs.
- Builds an HTML draft of the content on readthedocs, and sends the URL to the reviewer.
- The SME replies by adding comments to the pull request or as preferred (email, hardcopy, etc.).
- The doc team incorporates the changes. If the doc team has further questions, the doc team submits the doc for tech review again.
- The doc team publishes the documentation.