MEP-0019
Element to Record Reviews
This page proposes adding a new informational element review to the Mallard core, as a child element of the revision element.
| Authors: | Shaun McCance |
|---|---|
| Created: | 2019-12-07 |
| Status: | proposed (2019-12-07) |
| Target: | 1.2 |
| Issue: | https://github.com/projectmallard/projectmallard.org/issues/74 |
| History: |
This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.
Background
Mallard provides the revision element to record information about the current revision, including multiple version numbers, the date, and the status. While you can use the revision element to mark a page as needing reviews, there is no standard way to record those reviews when they happen.
Proposal
This page proposes adding a new review element as a child element of the informational revision element. Each revision element could have any number of review elements, with each review element recording one review done against that revision.
Each review element can optionally contain each of the following attributes:
- type
The type of review being performed, such as a peer review, technical review, or final review. Any value would be allowed, but we should make recommendations for common values. These values should be coordinated with review status flags in MEP-0021: Revision Status Flags. Possible values include gap, markup, draft, devel, tech, style, legal, copy, and final.
- status
The status as reported by the reviewer. This might indicate that the page is ok, or that it needs work. Any value would be allowed, but we should make recommendations for common values.
- by
An identifier for the person doing the review. This could be an email address or just a username. This is different from how the comment element uses the cite element to record the name of the person. We may consider the by attribute in other places, such as comment and revision.
- date
The date the review was done, preferably in the One True Date Format.
- href
A URL where the full text of the review can be found.
Additionally, the review element can optionally contain any general block content. This can be used to write the review directly in the page.
Examples
This section is not yet written. Discuss this proposal on mallard-list.
Internationalization
Since reviews are internal notes amongst teams, translating them is likely not the best use of time. Translation tools should consider making the block content of a review element untranslatable by default.
Compatibility and Fallback
This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.
The fallback behavior for a new info element is that is is ignored. The review element is not intended to be displayed to users in normal circumstances, so there is no loss of functionality when using older tools that do not support this proposal.
Comparison to Other Formats
Although both DocBook and DITA provide mechanisms for recording revisions and status information, neither provides a comparable mechanism for recording reviews. This is usually left to external systems.
