Elements for pre-publish review

The draft-comment element allows review and discussion information to be embedded within topic mark-up. The more basic XML comment can also be used for a similar purpose.

In a typical documentation process, incomplete information will often prevent the completion of a topic. To help track and manage the incomplete information, an author can add draft-comment phrase elements. The draft-comment element is also useful during the peer review and editing stages to leave remarks or suggestions for the author to consider or implement.

The draft-comment element has an author attribute, used to record the name of the author of the comment. An example of the mark-up is:
<p>The MY11 XRW uses an AHA turbocharger.
  <draft-comment author="Leo">
     Check if this changed after product meeting
  </draft-comment>
<p>

The draft-comment element should not be confused with the required-cleanup element. The required-cleanup element is intended only for identifying text in imported topics (typically, topics converted from XHTML to DITA) where the mark-up was not cleanly converted. In other words, required-cleanup content needs a human author to manually correct the mark-up to preserve the original intent.

Any draft-comment content will normally be removed during the publishing process. However, some authoring tools allow draft-comment elements to be deliberately included in the output.

The draft-comment element is not allowed in some structures. An alternative is to use standard XML comment special element. Many authoring tools allow the addition of XML comments in the WYSIOO editor.

The mark-up of an XML comment is shown in the example:
<!-- Check that the last step is required for MY11 model -->