Performing a Technical or Editorial Review
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.
Levels of Edit
The doc team uses these terms to describe different types of editorial work.
| Level of Edit | Description |
|---|---|
| Developmental edit | Typically requested early in the documentation cycle, and for larger projects. Includes an assessment of whether the planned material addresses the needs of all of the audiences (open source, partners; learner, course team, developer, researcher, installer), is organized within existing documentation in a way that makes sense for both new and existing users, and has been appropriately divided into conceptual and procedural topics for each audience. It also is an opportunity to identify areas where too much, or too little, detail is provided for each audience. Because the time that we can devote to stories is relatively short, this level of edit also includes what is sometimes called a stylistic edit, to identify problems with clarity, flow, or transitions, and to indicate where additional cross-referencing might be useful. |
| Copy edit | Typically requested for all documentation projects. The most thorough reading, the copy edit identifies grammar, usage, and spelling errors, and applies the guidelines in the MS Manual of Style and the edX Style Guide. This edit identifies problems with consistency, and choices that might negatively affect accessibility and translation. Awkward or wordy sentences are pointed out and alternatives suggested. For small projects, this edit provides an opportunity to make suggestions that might otherwise be part of a developmental or stylistic edit. |
| Sanity check | Typically requested to finalize a complex or large project, or when time to publication is very limited. A sanity check identifies any problems that would prevent the published files from being built correctly, oversights in the markup that affect readability, and problems with directives such as include and only. A sanity check also identifies spelling errors and other annoyances that might have been introduced late in the cycle or in haste. |