Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. 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.
  2. The SME replies by adding comments to the pull request or as preferred (email, hardcopy, etc.).
  3. The doc team incorporates the changes. If the doc team has further questions, the doc team submits the doc for tech review again.
  4. The doc team publishes the documentation.

Levels of Edit

The doc team uses these terms to describe different types of editorial work. 

Level of EditDescription
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.