Jorsek Strategies

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

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

Publishing

We use the PDF Generator and content portal publishing engines.

Guidelines

  • Use the “jorsek_pdf” publishing scenario
    Note: Should there be anything wrong with the “jorsek_pdf” publishing scenario, fall back to the “DITA-OT 2.5.4 Jorsek 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

  • Use the “Generate Release Notes from JIRA Issues” report to generate release notes from Jira.
  • 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.

Use Avoid
“In the following example” “In the example below”
“In the previous example” “In the example above”
Nouns Personal, demonstrative, and possessive pronouns