Sometimes the documentation team needs an engineer, PM, or both 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. Below is our suggestion for a .
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 a new or changed document for tech review in one of the following ways.
- Submits a pull request for the changes, and tags the engineer in the pull requestuses the Doc Team Pull Request Template to identify and tag SMEs.
- Builds a an HTML draft of the content on readthedocs, and sends the URL of the pages to be tech reviewed to the engineer.
- Creates a PDF of the document, adds comments to the PDF, and sends the PDF to the engineer or PM.
- Mark: We could add the PDF to our Dropbox folder, but that would mean granting a lot of users access to that folder. Is there a better way to do this?
- Question: Is there a list of engineering contacts we can use?
- reviewer.
- The SME replies by adding comments to the pull request or PDF, or by sending comments about the HTML.Question: What's a reasonable turnaround time?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.