Under maintenance

Heretto Help

Draft Comment Element (draft-comment)

The draft-comment element facilitates review and discussion of topic contents by embedding questions, comments, and notes directly within DITA content during the authoring process.

The draft-comment element serves these primary purposes:

  • Documents the source and rationale for content changes, creating an audit trail within the DITA source

  • Tracks references to external requirements, tickets, or source documents that drove content updates

  • Captures metadata about changes through attributes (@author, @time) for compliance and quality tracking

  • Enables conditional rendering to present change history in draft outputs for stakeholder visibility

Key characteristics of the draft-comment element:

  • Can contain the same rich content as body elements, including paragraphs, lists, and tables

  • Supports tracking attributes (@author, @time, @disposition) for review management

  • Has a default @translate value of "no" to prevent translation of internal comments

  • Can be placed in numerous contexts throughout topic and map structures

Content within the draft comment element generally follows these processing rules:

  • By default, processors should strip draft comments from production output

  • Processors should provide a mechanism to render draft comments in review builds

  • When rendered, draft comments typically appear with visual distinction from regular content

  • Metadata attributes may be displayed to show comment attribution and status

  • Draft comments should not affect the numbering or structure of surrounding content

Use draft-comment to:

  • Document why specific content was changed, including references to tickets, requirements, or standards

  • Track the source of technical specifications, legal requirements, or customer feedback

  • Create an audit trail for regulatory compliance or quality management systems

  • Preserve change history when migrating content between systems or versions

  • Include temporary notes that should appear in draft builds but not in production output

Tip:

Modern usage patterns for draft-comment:

  • In CCMS environments, use draft-comment for change tracking rather than review management (reviews typically happen through dedicated CCMS workflows)

  • Consider establishing team conventions for draft-comment content, such as always including ticket numbers or document references

  • Some teams include draft-comments in draft outputs to provide transparency about content changes to stakeholders

The draft-comment element used to request additional information and track review status in a concept topic in the Heretto CCMS Content Editor:

Layer 1

The DITA source of the draft-comment element with review tracking attributes and surrounding context:

<concept id="coffee-extraction" xml:lang="en-us">
    <title>Coffee Extraction Principles</title>
    <shortdesc>Coffee extraction is the process of dissolving soluble compounds from ground coffee beans using water as a solvent.</shortdesc>
    <prolog>
        <author translate="no" type="creator">Technical Writer &lt;writer@example.com&gt;</author>
    </prolog>
    <conbody>
        <p>The extraction process involves several key variables that determine the quality and characteristics of the final brew:</p>
        <ul>
            <li>
                <p>Water temperature affects the rate of extraction and solubility of different compounds. <draft-comment author="J.Smith" time="2025-05-15">Updated temperature range from 195-205°F to 195-200°F based on SCAA 2025 guidelines (ticket PROD-4827)</draft-comment>Optimal brewing temperature ranges from 195-200°F (90-93°C). Higher temperatures increase extraction speed but can lead to over-extraction of bitter compounds.</p>
            </li>
            <li>
                <p>Grind size determines the surface area exposed to water. Finer grinds extract more quickly but risk channeling and uneven extraction.</p><draft-comment author="M.Chen" time="2025-04-20">Added micron measurements per customer feedback in support case #8234. Engineering team confirmed these ranges in lab testing.</draft-comment>
                <ul>
                    <li>Espresso: 200-400 microns</li>
                    <li>Pour over: 600-800 microns</li>
                    <li>French press: 800-1000 microns</li>
                </ul>
            </li>
            <li>
                <p>Contact time between water and coffee grounds must be optimized for the brewing method. Too short results in under-extraction; too long causes over-extraction.</p><draft-comment author="K.Johnson" time="2025-06-01">Legal review requested we include disclaimer about commercial vs home brewing times due to liability concerns (LEGAL-2025-067)</draft-comment>
                <note type="important">Contact times listed are for home brewing applications. Commercial equipment may require different parameters.</note>
            </li>
            <li>
                <p>Water quality and mineral content significantly impact extraction efficiency and flavor development.</p><draft-comment author="T.Williams" time="2025-05-28">Section rewritten following R&amp;D water chemistry study (DOC-REF: WC-2025-Q2). Previous version archived in CMS version 3.2.1</draft-comment>
                <p>Target water parameters include:</p>
                <ul>
                    <li>Total hardness: 50-175 ppm CaCO3</li>
                    <li>Alkalinity: 40-70 ppm</li>
                    <li>pH: 6.5-7.5</li>
                    
                </ul>
            </li>
        </ul>
    </conbody>
</concept>