Heretto Strategies

Establishing content development strategies promotes consistency and reduces questions about the development process.

Remember: We develop the Heretto Strategies with our content needs in mind. We recommend developing your own strategies that align with your organization goals.

Publishing

We use the Heretto PDF Generator and Heretto Deploy publishing engines.

Guidelines

  • Use the “heretto_pdf” publishing scenario
    Note: Should there be anything wrong with the “heretto_pdf” publishing scenario, fall back to the “DITA-OT 2.5.4 Heretto PDF” scenario.
  • Apply the appropriate customer-facing DITAVAL.
    Note: For general PDF publishes, use the “customer_facing_print” DITAVAL.

Release Details

We document changes for every major release of our product.

Guidelines

  • Group release notes together into topics based on the interface area they affect.
  • In each topic, include “New” and “Fixed” sections.
  • Organize release notes by using the unordered list element.
  • Begin each release note with a past tense verb. For example, Fixed locking issues that prevented locks from releasing.
  • Include the related Jira story information in each entry.
  • Conditionalize the Jira story information with the @audience="internal" attribute.
  • Include screenshots or GIFs to illustrate new features or enhancements.

File Statuses

We use the following file statuses.

New
A resource that was created recently.
Obsolete
No longer needed or relevant.
Needs Reevaluation
Out of date, incorrect, or incomplete.
In Progress
In development or planned to be in development.
In Review
Being reviewed.
Approved
Finalized, can be published.
Ready to Merge
Approved and needs to be merged with a production branch.

Writing for Reuse Conventions

We develop content in a way that enables us to maximize reuse.

UseAvoid
“In the following example”“In the example below
“In the previous example”“In the example above
NounsPersonal, demonstrative, and possessive pronouns